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1.1 Overview 


This manual describes the system functions of Microsoft® Operating System/2 
(MS@ OS/2) that are new or modified for version 1.2. These functions let MS 
OS/2 programs use the operating system to carry out tasks such as reading and 
writing extended attributes for disk files, creating and using multiple-line entry 
fields, creating and accessing disk files through installable file systems, and 
displaying help text in a Presentation Manager application. 


MS OS/2 system functions are designed to be used in C, Pascal, and other high- 
level-language programs, as well as in assembly-language programs. MS OS/2 
programs request operating-system services by calling system functions. 


This chapter, “Introduction,” shows how to use this manual, provides a brief 
description of MS OS/2 calling conventions, illustrates function calls in various 
languages, and outlines MS OS/2 naming conventions. 


Chapter 2, “Overviews,” describes the new features and system functions for MS 
OS/2, version 1.2. This chapter explains the purpose of the functions and gives 
the operating-system concepts behind them. It also shows how the MS OS/2 sys- 
tem functions work together to carry out specific tasks. 


Chapter 3, “Functions and Messages Directory,” lists the MS OS/2, version 1.2, 
system functions and messages. Three categories of functions and messages are 
included: those that are new for MS OS/2, version 1.2; those that are updated, 
or changed, from MS OS/2, version 1.1; and those that contain corrections for 
errors that appeared in the Microsoft Operating System/2 Programmer’s Refer- 
ence, Volume 2 and Volume 3. The category of each item is clearly marked. 


This chapter defines the purpose of each function and each message, gives its 
syntax, describes any parameters, and gives possible return values. Many of the 
descriptions also show program examples that illustrate how the function or mes- 
sage is used to carry out simple tasks. 


Chapter 4, “Types, Macros, Structures,” lists and describes the new and updated 
data types and structures used by MS OS/2, version 1.2, system functions. — 


This manual is intended to describe the MS OS/2 system functions, messages, 
types, and structures that are new or that have been modified for MS OS/2, ver- 
sion 1.2. It does not explain how to use these functions to carry out specific 
tasks. For more information on this topic, see the Microsoft Operating System/2 
Programmer’s Reference, Volume 1. 


Also, this manual does not fully describe all MS OS/2 base system and Presenta- 
tion Manager functions. MS OS/2 base system functions enable programs to use. 
the operating system to carry out such tasks as reading from and writing to disk 
files; allocating memory; starting other programs; and using the keyboard, 
mouse, and video screen. Presentation Manager functions let programs use the 
multitasking, window-management, and graphics features of MS OS/2. For more 
information on MS OS/2 Presentation Manager functions, see the Microsoft 
Operating System/2 Programmer’s Reference, Volume 2. For more information on 
MS OS/2 base system functions, see the Microsoft Operating System/2 
Programmer’s Reference, Volume 3. 
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In addition, this manual references but does not discuss QuickHelp, the displa 
program for Microsoft documentation databases. For more information on 
QuickHelp, see Microsoft Operating System/2 Getting Started, available with the 
Microsoft OS/2 Presentation Manager Toolkit. 


1.2 How to Use This Manual 


This manual provides detailed information about each MS OS/2, version 1.2, 
system function, message, and structure. Each item has the format shown in 


Figure 1.1: 


Figure 1.1 
Sample Reference Page 


QO DosFreeSeg 


Change 


2) [ USHORT DosFreeSeg( se/) 
SEL sel; /» segment selector »/ 


© Parameters 
© Return Value 


© Comments 


@ Restrictions 


@ Example 


© See Also 


@ Changes 


The DosFreeSeg function frees the specified memory segment. This function 
accepts selectors for memory segments, shared-memory segments, huge- 
memory segments, aliased code segments, and resource segments allocated by 
DosGetResource. DosFreeSeg frees a shared-memory segment after the segment 
is freed by the last process accessing it. DosFreeSeg frees the code-segment 
selector for aliased code segments, but the corresponding data-segment selector 
remains valid until it is freed. 


The DosFreeSeg function is a family API function. 
sel Specifies the segment to free. 
The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 

ERROR_ACCESS_DENIED 
DosFreeSeg can be issued from ring 2, but the segment to free must be a ring-3 
segment. 


DosFreeSeg should not be used to free resource segments allocated by the 
DosGetResource2 function. To free those segments, use the DosFreeResource 
function. 


In real mode, the following restriction applies to the DosFreeSeg function: 


@ A code-segment selector (created by using the DosCreateCSAlias func- 
tion) and the corresponding data-segment selector are the same. Freeing 
one frees both. 


This example allocates three.segments of memory, then calls the DosFreeSeg 
function to free the memory: 


SEL sel; 
DosAllocHuge(3, 200, &sel, 5, SEG_NONSHARED) ; 


DosFreeSeg (sel); 


DosAllocHuge, DosAllocSeg, DosAllocShrSeg, DosCreateCSAlias, 
DosFreeResource, DosGetResource, DosGetResource2 


DosFreeSeg should not be used to free segments allocated by the 
DosGetResource2 function. 
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These are the elements shown in Figure 1.1: 


1 The name of the item and its MS OS/2, version 1.2, status (new, change, or 
correction). The name of the function, message, or structure appears on the left. 
Its MS OS/2, version 1.2, status is given on the right. 


2 The function, message, or structure syntax. The syntax specifies the number of 
parameters or fields and gives the type of each. It also gives the order (from left 
to right) that parameters must be pushed on the stack. Comments to the right 
briefly describe the purpose of the parameter. 


3 A description of the function, message, or structure, including its purpose and 
details of operation. 


4 A full description of each parameter or field, including permitted values and 
related structures. 


A description of the return value, including possible error values. 


5 
6 General comments about how the function, message, or structure can be used. 
7 Restrictions that affect how the function operates in real mode. 

8 


An example showing how the function or message can be used to accomplish a 
simple task. 


9 A list of related functions and messages. 
10 A summary of the item’s changes or corrections for MS OS/2, version 1.2. 


1.2.1 C Format 


In this manual, the syntax for MS OS/2 functions is given in C-language format. 
In your C-language sources, the function name must be spelled exactly as given 
in the syntax, and the parameters must be used in the order given in the syntax. 
This syntax also applies to Pascal program sources. 


The following example shows how to call the DosBeep function in a C-language 
program: 
/* Play a note for 1 second. */ 


DosBeep (660, /* 660 cycles-per-second */ 
1000); /* play for 1000 milliseconds */ 


1.2.2 MS OS/2 Include Files 


This manual uses many types, structures, and constants that are not part of stan- 
dard C language. These items, designed for MS OS/2, are defined in the MS 
OS/2 C-language include files provided with the Microsoft OS/2 Presentation 
Manager Softset and the Microsoft OS/2 Presentation Manager Toolkit. — 
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In C-language programs, the #include directive specifying os2.h, the MS OS/2 
C-language include file, can be placed at the beginning of the source file to 
include the definitions for the special types, structures, and constants. Although 
there are many MS OS/2 include files, the os2.h file contains the additional 
#include directives needed to process the basic MS OS/2 definitions. 


To speed up processing of the MS OS/2 C-language include files, many 
definitions are processed only if the C-language program explicitly defines a 
corresponding include constant. An include constant is simply a constant name, 
with the prefix INCL_, that controls a portion of the include files. If a constant 
is defined using the #define directive, the corresponding MS OS/2 definitions 
are processed. For a list of the include constants and a description of the MS 
OS/2 system functions they enable, see the Microsoft Operating System/2 
Programmer’s Reference, Volume 1. 


1.2.3 MS OS/2 Calling Conventions 


You must know MS OS/2 calling conventions to use MS OS/2 functions in other 
high-level languages or in assembly language. MS OS/2 functions use the Pascal 
(sometimes called the PLM) calling convention for passing parameters, and they. 
apply some additional rules to support dynamic-link libraries. The following rules 
apply: 


™ You must push the parameters on the stack. In this manual, each func- 
tion description lists the parameters in the order they must be pushed. 
The left parameter must be pushed first, the right parameter last. If a 
parameter specifies an address, the address must be a far address; that 
is, it must have the form selector:offset. The selector must be pushed 
first, then the offset. 


@ The function automatically removes the parameters from the stack as it 
returns. This means the function must have a fixed number of parame- 
ters. 


@ You must use an intersegment call instruction to call the function. This 
is required for all dynamic-link-library functions. 


™ The function returns a value, possibly an error value, in either the ax 
register or the dx:ax register pair. Only the di and si register values are 
guaranteed to be preserved by the function. MS OS/2 system functions 
may preserve other registers as well, but they do not preserve the flags 
register. The contents of the flags register are undefined; specifically, the 
direction flag in the register may be changed. However, if the direction 
flag was zero before the function was called, it will be zero after the 
function returns. 
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The following example shows how MS OS/2 calling conventions apply to the 
DosOpen function in an assembly-language program: 


EXTRN DOSOPEN:FAR 


name db "apo", O 

hFile dw (e) 

usAction dw fe) 

push ds ; filename to open 

push offset name 

push ds ; address of file handle 

push offset hFile 

push ds ; address to store action taken 
push offset usAction 

push ce) ; size of new file O100H 

push 100 

push fe) : file's attribute 

push 0010H ; create file if it does not exist 
push 0041H ; open file for writing, share with all 
push ie) ; reserved 

push fe) 

call DOSOPEN 


The following example shows how to call the same DosOpen function in a C- 
language program. In C, the DosOpen function name, parameter types, and con- 
stant names are defined in os2.h, the MS OS/2 C-language include file. 


# include <os2.h> 


HFILE hfile; 
USHORT usAction; 


DosOpen ("abc", /7* filename to open a 
&hfile, /7* address of file handle */ 
&usAction, /* address to store action taken */ 
100L, /* size of new file / 
FILE_NORMAL, /* file's attribute */ 
FILE_CREATE, /* create file if it does not exist */ 
OPEN_SHARE_DENYNONE | /* share with all */ 
OPEN_ACCESS_WRITEONLY, /* open for writing */ 
OL) ; /* reserved . 


1.2.4 Bit Masks in Function Parameters 


Many MS OS/2 system functions accept or return bit masks as part of their 
operation. A bit mask is a collection of two or more bit fields within a single * 
byte, or a short or long value. Bit masks provide a way to pack many Boolean 
flags (flags whose values represent on/off or true/false values) into a single 
parameter or structure field. In assembly-language programming, it is easy to 
individually set, clear, or test the bits in a bit mask by using instructions that 
modify or examine bits within a byte or a word. In C-language programming, 
however, the programmer does not have direct access to these instructions, so 
the bitwise AND and OR operators typically are used to examine and modify the 
bit masks. 


Because this manual presents the syntax of MS OS/2 system functions in C- 
language syntax, it also defines bit masks in a way that is easiest to work with 
using the C language: as a set of constant values. When a function parameter is a 
bit mask, this manual provides a list of constants (named or numeric) that 
represent the correct values used to set, clear, or examine each field in the bit 
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mask. For example, the fbType field of the VIOMODEINFO structure in the 
VioSetMode function specifies three values: VGMT_DISABLEBURST, 
VGMT_GRAPHICS, and VGMT_OTHER. These represent the “set” values of 
the first three fields in the bit mask. Typically, the description associated with 
the value explains the result of the function if the given value is used (that is, 
when the corresponding bit is set). Generally, the opposite result is assumed 
when the value is not used. For example, using VGMT_GRAPHICS in the 
fbType field enables graphics mode; not using it disables graphics mode. 


1.2.5 Structures 


Many MS OS/2 system functions use structures as input and output parameters. 
This manual defines all structures and their fields using C-language syntax. In 
most cases, the structure definition presented is copied directly from the C- 
language include files provided with the Microsoft C Optimizing Compiler. Occa- 
sionally, an MS OS/2 function may have a structure that has no corresponding 
include-file definition. In such cases, this manual gives an incomplete form of the 
C-language structure definition to indicate that the structure is not already 
defined in an include file. 


1.3 Naming Conventions 


In this manual, all parameter, variable, structure, field, and constant names con- 
form to MS OS/2 naming conventions. MS OS/2 naming conventions are rules 
that define how to create names that indicate both the purpose and data type of 
an item used with MS OS/2 system functions. These naming conventions are 
used in this manual to help you readily identify the purpose and type of the func- 
tion parameters and structure fields. These conventions are also used in most 
MS OS/2 sample program sources to make the sources more readable and infor- 
mative. 


1.3.1 Parameter and Field Names 


With MS OS/2 naming conventions, all parameter and field names consist of up 

’ to three elements: a prefix, a base type, and a qualifier. A name always consists 
of at least a base type or a qualifier. In most cases, the name also includes a 
prefix. 


The base type, always written in lowercase letters, identifies the data type of the 
item. The prefix, also written in lowercase letters, specifies additional informa- 
tion about the item, such as whether it is a pointer, an array, or a count of 
bytes. The qualifier, a short word or phrase written with the first letter of each 
word uppercase, specifies the purpose of the item. 


There are several standard prefixes and base types. These are used for the data 
types most frequently used with MS OS/2. 
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1.3.1.1 Prefixes 


The following standard prefixes are used in MS OS/2 naming conventions: 


Prefix 


Pp 


np 


off 


1.3.1.2 Base Types 


Description 


Pointer. This prefix identifies a far, or 32-bit, 
pointer to a given item. For example, pch is a far 
pointer to a character. 


Near pointer. This prefix identifies a near, or 16-bit, 
pointer to a given item. For example, npch is a near 
pointer to a character. 


Array. This prefix identifies an array of two or more 
items of a given type. For example, ach is an array 
of characters. 


Index. This prefix identifies an index into an array. 
For example, ich is an index to one character in an 
array of characters. 


Count. This prefix identifies a count of items. It is 
usually combined with the base type of the items 
being counted instead of the base type of the actual 
parameter. For example, cch is a count of charac- 
ters even though it may be declared with the type 
USHORT. 


Handle. This prefix is used for values that uniquely 
identify an object but that cannot be used to access 
the object directly. For example, hfile is a file han- 
dle. . 


Offset. This prefix is used for values that represent 
offsets from the beginning of a buffer or a structure. 
For example, off is the offset from the beginning of . 
the given segment to the specified byte. 


Identifier. This prefix is used for values that identify 
an object. For example, idSession is a session . 
identifier. 


The following standard base types are used in MS OS/2 naming conventions: 


Base type 


i. 


ch 


Type/Description 


BOOL. A 16-bit flag or Boolean value. The qualifier 
should describe the condition associated with the 
flag when it is TRUE. For example, fSuccess is_ 


- TRUE if successful, FALSE if not; fError is TRUE 


if an error occurs and FALSE if no error occurs. 
For objects of type BOOL, a zero value implies 
FALSE, a nonzero value implies TRUE. 


CHAR. An 8-bit signed value. 
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Base type Type/Description 
So SHORT. A 16-bit signed value. 
lL LONG. A 32-bit signed value. 
uch UCHAR. An 8-bit unsigned value. 
us USHORT. A 16-bit unsigned value. 
ul ULONG. A 32-bit unsigned value. 
b BYTE. An 8-bit unsigned value. Same as uch. 
SZ CHAR[ ]. An array of characters, terminated with a 
null character (the last byte is set to zero). 
fb UCHAR. An array of flags in a byte. This base type 


is used when more than one flag is packed in an 
8-bit value. Values for such an array are typically 
created by using the logical OR operator to com- 
bine two or more values. 


fs USHORT. An array of flags in a short (16-bit 
unsigned value). This base type is used when more 
than one flag is packed in a 16-bit value. Values for 
such an array are typically created by using the logi- 
cal OR operator to combine two or more values. 


fi ULONG. An array of flags in a long (32-bit unsigned 
value). This base type is used when more than one 
flag is packed in a 32-bit value. Values for such an 
array are typically created by using the logical OR 
operator to combine two or more values. 


Sel SEL. A 16-bit value used to hold a segment selec- 
tor. 


The base type for a structure is usually derived from the structure name. An MS 
OS/2 structure name, always written in uppercase letters, is a word or phrase 
that describes the size, purpose, and/or intended content associated with the 
type. The base type is typically an abbreviation of the structure name. The fol- 
lowing are the base types for the structures described in this manual: 


avldt fsinf matlf ptrdd 
cbnd fsqbf mlectl sbcd 
dena fsts2 mlefrd stsdata 
eaop fuc mlemrg swhblk 
efd fur mleovr ti 

fat gea mlesrch viocreg 
fea geal nmpsmst __-viofcsz 
feal hei param vioin 
findbuf2 hinit pres | viomi 
fic ht prfpro viosett 
fir kbci progde viOSZ 
fm kbhw progt viouline 
frwc Idtaddr progti wprm 


fsc lis ptrcbf 
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1.3.2 Constant Names 


A constant name is a descriptive name for a numeric value used with an MS 
OS/2 function. All constant names are written in uppercase letters and have a 
prefix derived from the name of the function, object, or idea associated with the 
constant. The prefix is followed by an underscore (_) and the rest of the con- 
stant name, which indicates the meaning of the constant and may specify a 
value, action, color, or condition. A few common constants do not have 
prefixes—for example, NULL is used for null pointers of all types, and TRUE 
and FALSE are used with the BOOL data type. 


1.4 Notational Conventions 


The following notational conventions are used throughout this manual: 


Convention 


bold 


Meaning 


Bold type is used for keywords—for example, the 


italics 


monospace 


names of functions, data types, and structures. 
These names are spelled exactly as they should 
appear in source programs. 


Italic type is used to indicate the name of an 
argument; this name must be replaced by an 
actual argument. Italics are also used to show 
emphasis in text. 


Monospace type is used for example program- 
code fragments. 
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2.1 Introduction 


This chapter describes the MS OS/2 system functions in individual-topic sec- 
tions. Each section describes a portion of MS OS/2 that lets an application carry 
out a specific task or set of related tasks. For example, the section about the 
multiple-line entry field (MLE) defines basic MLE terms, describes the role of 
multiple-line entry-field messages, and illustrates how to use those messages. 


Each topic section in this chapter gives a general description and programming 
samples. Each section discusses the purpose and operation of pertinent MS 
OS/2 functions. The programming samples show how to use those MS OS/2 
functions in applications to carry out useful tasks. 


In many cases, it is assumed that you have basic knowledge of some other por- 
tions of MS OS/2. Each section lists the prerequisites for understanding the con- 
cepts and terms described in that section. 


2.2 Installable File Systems 


This section describes how MS OS/2 enables programs to use installable file sys- 
tems. A file system is the combination of software and hardware that supports 
storing information on a storage device. An installable file system is a file system 
whose software can be installed when the operating system starts. MS OS/2 sup- 
ports installable file systems and permits users to have multiple file systems 
active at the same time. 


This section also describes some of the MS OS/2 functions that let programs 
create, read, and write data files in installable file systems. Because installable 
file systems are not available with releases of MS OS/2 prior to version 1.2 or 
with MS-DOS6®, versions 2.0 through 3.3, programs that use the family applica- 
tion programming interface (family API) cannot use functions that are specific to 
installable file systems. 


2.2.1 About Installable File Systems 


In MS OS/2, version 1.2, users install a file system by specifying the file-system 
components in the config.sys file. The file-system software consists of device 
drivers that access storage devices and dynamic-link libraries that control the 
format of information on a device and manage the flow of data to and from the 
device. The user must use the device command to specify the device driver and 
the ifs command to specify the dynamic-link library. MS OS/2 loads the device 
driver and dynamic-link library and initializes a specific device for use as a file 
system. 


MS OS/2, version 1.2, has two file systems: the file allocation table (FAT) file 
system and the high-performance file system (HPFS). These file systems define 
how information is organized on the storage devices. Both file systems create 
data files supported by one or more tables that specify the location and size of 
the data files on the storage device. 


The file allocation table (FAT) file system is the default file system for MS 
OS/2; it does not need to be installed. The FAT file system, used in previous 
releases of MS OS/2 and also in MS-DOS, controls storage of data files for 
fixed and floppy disks. The FAT file system is hierarchical, allowing multiple 
directories on the disk. Each directory can contain one or more files. The 
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distinguishing feature of the FAT file system is its 8.3 filename convention. 
Under this convention, the filename consists of a filename (up to eight charac- 
ters), a separating period (.), and a filename extension (up to three characters). 


The high-performance file system (HPFS) is an installable file system for MS 
OS/2. It is an hierarchical file system and allows for multiple directories. HPFS 
controls storage of data for fixed disks. Filenames under HPFS can be any prac- 
tical length and can contain characters that are not valid for the FAT file sys- 
tem, for example, spaces and underscores (__). In many cases, accessing files 
under HPFS is faster than accessing similar files under the FAT file system. 


A user can choose either or both file systems. Programs must be able to work 
with any file system. Fortunately, MS OS/2 provides a common set of file-system 
functions that are not dependent upon a particular file system; it also gives 
guidelines for working with file systems, such as specific filename conventions. 


2.2.1.1 File-System Functions 


MS OS/2 provides a standard set of file-system functions. This means that pro- 
grams can create, open, read, write, copy, and delete files and directories by 
using the same functions regardless of which file system is used. When a pro- 
gram Calls a file-system function, MS OS/2 passes the request to the dynamic- 
link library that supports the file system. Most file-system processing, such as 
validating filenames, is carried out by the dynamic-link library. If an error 
occurs, the file system returns the error to MS OS/2, which then passes it back 
to the calling program. 


Occasionally, a file system may extend the standard set of file-system functions 
by providing file-system control functions. The control functions are specific to 
the given file system. A program can call a control function by using the 
DosFSCtl function, which directs MS OS/2 to pass the control-function informa- 
tion to the dynamic-link library for the particular file system. 


2.2.1.2 File-System Volume 


MS OS/2 allows more than one file system on a single storage device. If the 
device can have more than one logical partition (or volume), each partition can 
be initialized as an MS OS/2 partition and given a valid MS OS/2 file system. 
For each volume, MS OS/2 determines the type of file system the first time the 
volume is accessed by a function or when the media in the drive changes. After 
that, MS OS/2 manages all input and output to that volume by using the 
corresponding dynamic-link library for the file system. 


MS OS/2 uses the volume label and serial number to ensure that the media in 
the drive does not change while there are outstanding requests for input and out- 
put. Each volume has a volume label and a 32-bit volume serial number, stored 
in a reserved location in logical sector zero at the time of formatting. If the 
volume label and serial number do not match, MS OS/2 signals the critical-error 
handler to prompt the user to insert the volume that has the specified serial 
number and label. MS OS/2 maintains the connection between the media and 
the volume label and serial number until all open files on the volume are closed 
and all search references and cache-buffer references are removed. The system 
redetermines the type of the file system and the volume label and serial number 
for the volume only when the media changes. 
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2.2.1.3 Local and Remote File Systems 


Installable file systems work with a variety of storage devices. A file system on a 
local device such as a disk drive or virtual disk is called a local file system. A file 
system on a remote device such as a disk drive on another computer is called a 
remote file system. A program can establish a connection to a local or a remote 
file system by using the DosFSAttach function. 


For a local file system, MS OS/2 uses a block device driver to handle input and 
output to the device. MS OS/2 automatically connects most (if not all) local file 
systems when it starts. However, a program can connect and disconnect (some- 
times called mount and dismount) additional file systems as needed. 


For a remote file system, the corresponding device driver typically accesses a 
communications or network device instead of a block device driver used to 
access disk hardware. Typically, the actual storage device is located on another 
computer, and the two computers communicate requests and data through a net- 
work connection. A program can connect a remote file system to a drive letter 
by using the DosFSAttach function. Once the connection is made, the program 
can access directories and files on the remote device simply by using the 
assigned drive letter, treating the remote device as if it were on the same com- 
puter. 


2.2.1.4 Pseudo-Character Device 


A program can attach a device name to a file system and use the file system as a 
pseudo-character device (also called a single-file device). Attaching a device 
name to a file system lets a program open the device associated with the file sys- 
tem as if it were a character device (for example, a serial port) and read 

from and write to the device by using the DosRead and DosWrite functions. 
Unlike with a character device, a program can use the DosChgFilePtr and 
DosFileLocks functions for working with a pseudo-character device. An MS 
OS/2 pseudo-character device name is a null-terminated string in the format of 
an MS OS/2 filename in a subdirectory called \dev. 


A file system that can be attached to a pseudo-character device is typically asso- 
ciated with a single disk file or with a special storage device such as a tape drive. 
The file system establishes a connection with the device and transfers requests 
and data between MS OS/2 and the device. The following example attaches the 
device associated with the file system bcrvmpcl to the pseudo-character device 
named \dev\host: 


BYTE bData[]; 
USHORT cbData; 


DosFSAttach ("\dev\host", “bervmpcl", bData, cbData, 0); 


If the program successfully attaches the file system, the program can then open 
the file \dev\host by using the DosOpen function, read host-created data by using 
the DosRead function, and write data and commands to the host by using the 
DosWrite function. This example assumes that the name bcrvmpcl corresponds 
to an installable file system and that the file system can perform the necessary 
host communication and translation. . 
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2.2.1.5 Filename Conventions 


Filename conventions are the rules used to form names that uniquely identify 
files in a given file system. Although each installable file system can have specific 
rules about how individual components in a directory or filename are formed, all 
file systems follow the same general conventions for combining components. For 
example, the FAT file system requires that file and directory names have the 8.3 
filename format, HPFS allows names to be any length, but both file systems use 
the backslash (\) character to separate directory names and the filename when 
forming a path. 


When creating names for directories and files or when processing names sup- 
plied by the user, programs should follow these general rules: 


1 Process a path as a null-terminated string. A program can determine maximum 
length for a path by using the DosQSysInfo function. 


2 Use any character in the current code page for a name, but do not use a path 
separator, a character in the range 0 through 31, or any character explicitly disal- 
lowed by the file system. Although a name can contain characters above 127, a 
program must be able to switch code pages if necessary to access the 
corresponding file. 


3 Compare names using a case-insensitive comparison. Names such as ABC, Abc, 
and abc are considered to be the same name. 


‘4 Use the backslash (\) and/or the forward slash (/) to separate components in a 
path. No other character is accepted as a path separator. 


5 Use the dot (.) as a directory component in a path to represent the current 
directory. 


6 Use two dots (..) as a directory component in a path to represent the parent of 
the current directory. 


7 Usea period (.) to separate components in a directory name or filename. Unless 
explicitly defined by a file system, there are no restrictions on the number of 
components in a name. 


2.2.1.6 Filenames in DOS-Compatibility Mode 


For compatibility with existing DOS 3.x programs, all file systems support the 
FAT file system’s 8.3 filename format. This means that programs running in 
DOS-compatibility mode can access files on non-FAT file systems if the 
filenames have the 8.3 format. To guarantee this rule, MS OS/2 automatically 
applies the 8.3 truncation rules to all filenames given in file-system requests from 
DOS-compatibility mode. 


2.2.1.7 Filenames in User Input 


Users often supply filenames as part of a program’s command line or in response 
to a prompt from the program. Traditionally, users have been able to supply 
more than one filename on the command line or in a prompt by separating the 
names with certain characters, such as a blank space. In some file systems, 
however, traditional separators can be used as valid filename characters. This 
means that some additional conventions are required to ensure that a program 
processes all characters in a name. 
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When a program processes arguments (including filenames) from its command 
line, the program should treat the double quotation mark (") and the caret (“) as 
quotation characters. All characters between the starting and closing double 
quotation marks should be processed as a single argument. The character 
immediately following the caret should be processed as part of the current argu- 
ment. In both cases, the quotation characters are discarded and not treated as 
part of the final argument. 


When a program processes two or more filenames from a dialog box or other 
prompt, it expects the user to enter each filename on a new line. For example, a 
Presentation Manager application should use a multiple-line entry field to prompt 
for multiple filenames. This makes the use of quotation characters unnecessary. 


When a program is started from File Manager, File Manager may construct a 
command line for the program. If the command line includes filenames, File 
Manager separates each argument with a space character and marks the end of 
the argument list with two null characters. Programs that start other programs by 
using the DosExecPgm function also can pass arguments using this convention 
or by using quotation characters. In practice, most programs receive a command 
line as a single, null-terminated string. Therefore, programs that use the Dos- 
ExecPgm function should prepare command lines as a single string with any 
filenames in the string enclosed in quotation marks. 


2.2.1.8 Metacharacters in Filenames 


To give the user a shortcut to entering long lists of names, programs that accept 
more than one filename on their command line can allow metacharacters in 
filenames. The metacharacters, the asterisk (*) and the question mark (?), 
represent placeholders in a filename. Although a name that contains metacharac- 
ters is not a complete filename, a program can use functions, such as DosFind- 
First and DosEditName, to expand the name (replace the metacharacters) to 
create one or more valid filenames. 


A program can expand a name with metacharacters to a list of filenames by 
using the DosFindFirst function. The asterisk (*) matches one or more charac- 
ters, including blanks. The question mark (?) matches one character, unless that 
character is a period (.). To match a period, the original name must contain a 
period. 


A program can create a new filename from an existing name by using the 

- DosEditName function. This function takes a template (a name with metacharac- 
ters) and expands it, using characters from an existing name. An asterisk (*) in 
the template directs the function to copy all characters in the existing name until 
it locates a character that matches the character following the asterisk. A ques- 
tion mark (?) directs the function to copy one character unless that character is 
a period. The period (.) in the template directs the function look for and move 
to the next period in the existing name, skipping any characters between the 
current position and the period. 


The metacharacters are illegal in all but the last component of a path. 
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2.2.1.9 File-System Errors 


Some MS OS/2 file-system functions return the following errors: 


Value Meaning 

ERROR_WRITE_PROTECT The disk in the drive is write- 
protected. 

ERROR_BAD_UNIT There is a breakdown of internal 


consistency in mapping between 
the logical drive and the device 
driver. Internal error. 


ERROR_NOT_READY The device is not ready. 


ERROR_BAD_COMMAND There is a breakdown of internal 
consistency between the expected 
capability of a device driver and 
its true capability. 


ERROR_CRC The device driver detected a 
cyclic redundancy check (CRC) 
mismatch. 

ERROR_BAD_LENGTH There is a breakdown of internal 


consistency between the expected 
length of a request packet and the 
true length. Internal error. 


ERROR_SEEK The device driver detected an 
error during a seek operation. 
ERROR_NOT_DOS_DISK The disk is not recognized as 


being manageable by MS OS/2. 


ERROR_SECTOR_NOT_FOUND _ The device is unable to find the 
specific sector. 


ERROR_OUT_OF_PAPER The printer is out of paper. 
ERROR_WRITE_FAULT Other write-specific error. 
ERROR_READ_FAULT Other read-specific error. 
ERROR_GEN_FAILURE Other error. 


There are also errors defined by and specific to the specific device driver. These 
are indicated by either OxFF or OxFE in the high byte of the error code. 


2.2.2 Summary 
The following MS OS/2 file-system functions work with installable file systems: 
DosCopy Copies a file or subdirectory. | 
DosEditName Transforms a source string using an editing string. 


ie Performs file I/O (locking, unlock, seek, read, and write opera- 
tions). 


. Chapter 2: Overviews 23 
pat dices esrb dtl oes ibaa a ea ae i ane Oe YRS Eni oc ot la Ni arbor Tc baits ect Ut 


DosFindFirst2 Finds the first file that matches a specified filename and attri- 
butes. 


DosFSAttach Attaches or detaches a drive or pseudo-character device from a 
remote file system. 


DosFSCtl Calls file-system functions that are not part of the standard I/O func- 
tions. 


DosGetResource2 Retrieves a resource for a module. 
DosMkDir2 Creates a directory. 

DosOpen2 Opens or creates a file with extended attributes. 
DosQFSAttach Queries information about an attached file system. 
DosSetPathInfo Sets information for a file or directory. 


DosShutdown Shuts down the file system. 


2.0 Extended Attributes 


This section describes how to use extended attributes to store information about 
your files and directories. Before reading this section, you should be familiar 
with the MS OS/2 file system. 


2.3.1 About Extended Attributes 


Extended attributes can be thought of as a list of facts attached to a file or direc- 
tory. MS OS/2 stores extended attributes separate from the file or directory so 
that the attributes do not affect the contents of the file or directory. An applica- 
tion uses extended attributes to provide a description of the file or directory, but 
does not place the description in the file or directory itself. 


Each extended attribute has two parts: a name and a value. The name is a null- 
terminated string; applications can choose any convenient name. The value is 
corresponding data; it can be text, a bitmap, or any binary data. The application 
that creates the extended attributes and the applications that read the extended 
attributes must recognize the format and meaning of the data associated with a 
given name. 


2.3.2 Using Extended Attributes 


Applications can examine, add, and replace extended attributes at any time. The 
DosOpenz2 function adds extended attributes to new or existing files; the Dos- 
MkDir2 function adds extended attributes to new directories. Any application 
can read the extended attributes by using the DosQFileInfo or DosQPathInfo 
function. Applications can also search for files that have specific extended attri- 
butes by using the DosFindlirst and DosFindNext functions. 


A file can have any number of extended attributes. Each extended attribute can 
be up to 64K long. For MS OS/2, version 1.2, the sum of all extended attributes 
for a file must not exceed 64K. 
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2.3.2.1 Naming Conventions 


Although an application can choose any name for the extended attributes it 
creates, other applications cannot read the extended attributes unless they also 
recognize the corresponding format. Because many applications use extended 
attributes consisting of text, bitmaps, and other similar data, a set of names has 
been adopted to help identify these formats when used in extended attributes. 
An application need not be limited to this set of standard extended attributes, 
but should use it as a way for many applications to access a common set of 
information. 


The names for all standard extended attributes use a dot (.) as a prefix. The 
leading dot is considered reserved, so no application should define extended 
attributes that start with a dot. Also, extended attributes that start with the char- 
acters $, @, &, and + are reserved for system use. To ensure that its extended 
attributes are unique, an application should use the vendor and application name 
as a prefix for application-specific extended attributes. For example, Microsoft 
Excel would use MS EXCEL.MYSTUFF, MS EXCEL.MORESTUFF, and so 
forth. 


2.3.2.2 Data-Type Conventions 


Extended attributes can contain any type of data. To identify the type of infor- 
mation, the first word of extended-attribute data should specify one of the fol- 
lowing data types: 


Value Meaning 

EAT_BINARY Binary data; the first word specifies length. 

EAT_ASCI ASCII text; the first word specifies length. 

EAT_BITMAP Bitmap data; the first word specifies length. 

EAT_METAFILE Metafile data; the first word specifies length. 

EAT_ICON Icon data; the first word specifies length. 

EAT_EA ASCII name of associated data; the first 
word specifies length. 

EAT_MVMT Two or more consecutive extended-attribute 
values; each value has a explicitly specified 
type. 

EAT_MVST Two or more consecutive extended-attribute 
values; all values have the same type. 

EAT_ASN1 _ ASN.1 field data. 


In all cases, the length specifies the number of bytes of data. Other values for 
data types, in the range 0x0000 through 0x7FFF, can be used for user-defined 
extended attributes. User-defined data should also specify the length. 

For example, here is how to represent the string “Hello”: 


EAT_ASCII 0005 Hello 


Settee 
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2.3.3 Standard Extended Attributes 


2.3.3.1 


TYPE 


The standard extended attributes are listed in the following sections. The field 
format follows the data-type conventions given previously. A field can be a 
multivalue or single-value field. 


The .TYPE extended attribute indicates the type of file. It is similar to the ear- 
lier use of filename extensions. The following file types are predefined: 


Plain Text 

OS/2 Command File 
DOS Command File 
Executable 

Metafile 

Bitmap 

Icon 

Binary Data 
Dynamic Link Library 
C Code 

Pascal Code 

BASIC Code 
COBOL Code 
FORTRAN Code 
Assembler Code 
Library 

Resource File 


Applications can use their own type names, such as Microsoft Excel Chart. The 
first words in the type name should be the name of the vendor and the applica- 
tion. For example, Microsoft Excel Chart, Microsoft Excel Worksheet, Lotus 
1-2-3 Spreadsheet. 


Entries should be ASCII. Case is important. 


The performance of extended attributes is dependent on the file system. Because 
some file systems store extended attributes in first-in/first out (FIFO) order, it is 
important to write the .TYPE entry first so that File Manager can access, that 
information quickly. 


2.3.3.2 .KEYPHRASES 


The .KEYPHRASES extended attribute specifies text key phrases for the file. 
Such phrases can be used for a database-style search or to help the user under- 
stand the nature of the file. 


If there is more than one key phrase, each should be stored in a separate entry 
in a multivalue field. Each entry should be ASCII. 


2.3.3.3 .SUBJECT 


The .SUBJECT extended attribute contains a brief summary of the file’s content 
and/or purpose. This attribute should be less than 40 characters long. 


This field should be a single-value ASCII entry. 
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2.3.3.4 .COMMENTS 


The .COMMENTS extended attribute contains miscellaneous notes about the 

file. It can be a multivalue field and be of any type. This field is intended as a 

reminder note. For example, it could contain some notes about the intent of a 
file or a picture. 


2.3.3.5 .HISTORY 


The .HISTORY extended attribute lists the history of a file’s modification. It 
lists the author of the file and all subsequent changes. Each action entry should 
be a separate field in a multivalue field. Each entry should be ASCII. 


The application can let the user decide when an entry is placed into the history 
field, to avoid unnecessary file growth. For example, there are some cases when 
it is important to note when a document is printed; however, it is probably 
unnecessary to note every time the file was printed. 


2.3.3.6 .VERSION 


The .VERSION extended attribute is a version number of the file format (for 
example, Excel Worksheet 1). 


This attribute should be ASCII or binary. It should be modified only by the 
application. This attribute can also be used to indicate an application or 
dynamic-link library version. 


2.3.3.7 .ICON 


The .ICON extended attribute specifies the icon to be used for the file represen- 
tation, whether in File Manager or when minimized. File Manager can use the 
-TYPE entry to determine the default application to run and to determine the 
default icon for that type of file. If there is a ICON entry, however, it is used 
instead of the icon associated with a particular type. 


If the data type is for an icon, the icon data follows. It is best to provide as 
much icon information as possible. Ideally, an icon should be 64-by-64 bits in 
8-color, device-independent format. 


Executable files should simply store the binary icon data in this extended attri- 
bute. They should use the .ASSOCTABLE extended attribute to install icons 
for data files. 


2.3.3.8 .ASSOCTABLE 


- The .ASSOCTABLE extended attribute contains association data for a file. It is 
created by the Microsoft Operating System/2 Resource Compiler (re), from a 
table with the following form: 

ASSOCTABLE -assoctable -id 


BEGIN 
"type name", "extension", [flags], [icon filename] 


END 
The .ASSOCTABLE extended attribute contains information that associates 


icons with the data files an application creates. The file-association table associ- 
ates icons by data type. 
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The .ASSOCTABLE extended attribute allows an application to indicate the 
type, extension, and icon for the data files it recognizes. It also contains an own- 
ership flag. This data can be installed automatically by File Manager. 


For example, the table for Microsoft Excel could be: 


"MS Excel Worksheet", "XLS", AF_DEFAULTOWNER, excel.sheet.icon 
"MS Excel Chart", "XLC", AF_DEFAULTOWNER, excel.chart.icon 


The flag entry indicates if the application owns or merely recognizes the type. 
The icon file contains an icon for that data type. 


2.3.3.9 .HPFSNAME 


The .HPFSNAME attribute is used when an application attempts to write a 
file with a long name to a file system that does not support long names. The 
application should generate a unique short name for the file and notify the user 
of the new short name. It should then save the original (long) name in the 
-HPFSNAME extended attribute. 


When a file is copied from a system that uses short names to a system that uses 
long names, the application should check the .HPFSNAME extended attribute. 
If a value is present, the application should allow the file to be renamed to a 
long name. The .HPFSNAME extended attribute should then be removed. 


2.3.3.10 Supporting Extended Attributes 


To support extended attributes, applications should do the following: 


om, 


Fill in the .ASSOCTABLE extended attribute for all major file types that the 
application recognizes or uses. 


_ Fill in the .ICON extended attribute for executable files. 
Set the .TYPE field for data files it creates. 
Fill in and use the .HPFSNAME extended attribute as appropriate. 
Support .HISTORY and .VERSION. 
Support the other standard extended attributes as appropriate. 


onrh W NY 


2.3.3.11 Multivalue Data-Type Fields 


In many cases, extended attributes need to store more than a single piece of 
information. For example, an extended attribute can store a list of names of peo- 
‘ple to whom a mail document was sent. The multivalue formats specify how indi- 
vidual pieces of data are stored. 


In a multivalue field, the first entry in the list is assumed to be the default. For 
example, suppose the .TYPE entry contains Text and C Code. Text is the 
default type. If C Code is the first entry in the list (C Code and Text), then C 
Code is the default type. 


2.3.3.12 Multivalue, Multitype Attributes 


The EAT_MVMT type allows a single extended attribute to contain several 
pieces of information; each piece of information can be a different type. 
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2.3.3.13 Multivalue, Single-Type Attributes — 


The EAT_MVST type sets up a multivalue field in which each piece of informa- 
tion is of the same type. 


2.3.3.14 ASN.1 
The EAT_ASN1 type is an ISO standard for describing multivalue data streams. 


2.3.3.15 Include Extended-Attribute Type 


The EAT_EA type indicates that the data is continued in another extended- 
attribute entry associated with the file. Among other things, this allows for 
extended attributes greater than 64K (but not exceeding the limit per file). 


2.3.4 Summary 
The following MS OS/2 functions create and manage extended attributes: 


DosFindFirst2 Finds the first file that matches the specified filename and attri- 
butes. 


DosMkDir2 Creates a directory. 
DosOpen2 Opens or creates a file with extended attributes. 


DosQFileInfo Retrieves file information, including the date and time the file 
was created, the date and time it was last accessed, the date and time it was last 
written to, its size, and its attributes. It also returns information about a file’s 
extended attributes. 


DosQPathInfo Retrieves information about a file or directory. 


‘DosSetFileInfo Sets information about a file, including the date and time the 
file was created, the date and time it was last accessed, the date and time it was 
last written to, the size of the file, and its attributes. It can also set extended 
attributes for a file. 


DosSetPathInfo Sets information for a file or directory. 


2.4 Profile Manager 


This section describes how to use the MS OS/2 Profile Manager to store and 
retrieve information about your application and the system from the MS OS/2 
initialization files. Before reading this section, you should be familiar with the 
MS OS/2 initialization files. 


Profile Manager functions replace the MS OS/2 initialization-file functions 
described in the Microsoft Operating System/2 Programmer’s Reference, 
Volume 1. 


2.4.1 About Profile Manager 


Profile Manager enables applications to create their own initialization files snd to 
access the MS OS/2 initialization files, os2.ini and os2sys.ini. An initialization 
file is a convenient place to store information between sessions. Just as MS 
OS/2 uses the os2.ini and os2sys.ini files to store configuration information for 
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when it starts, an application can create initialization files that store information 
it uses to initialize windows and data when it starts. 


Because all initialization files are binary files, the user cannot view or edit them 
directly. A file consists of one or more sections; each section contains one or 
more settings, or keys. Each key consists of two parts: a name and a value. Both 
section names and key names are null-terminated strings. A key value can be a 
null-terminated string, a null-terminated string representing a signed integer, or 
individual bytes of data. 


The MS OS/2 initialization files, os2.ini and os2sys.ini, contain sections and set- 
tings used by the MS OS/2-system applications (such as Desktop Manager, Con- 
trol Panel, and Print Manager). Although applications can read settings from the 
MS OS/2 initialization files, only rarely will an application need to change a set- 
ting. One common task that does change the settings in the MS OS/2 initializa- 
tion files is adding a group and program list to Desktop Manager. For example, 
the installation program for an application can create a new group for the appli- 
cation and its related utilities by using Profile Manager functions. 


Once an initialization file is created, an application can rename, copy, move, 
and delete the file just like any other file. Although an application can also read 
and write to the file as if it were a binary file, the application should always use 
Profile Manager functions to access the contents of the file. 


2.4.2 Using Profile Manager 


You can use Profile Manager functions in character-based MS OS/2 programs as 
well as in Presentation Manager applications. A thread that calls Profile Manager 
functions must have initialized an anchor block by using the WinInitialize func- 
tion. You create an initialization file or open an existing one by using the 
PrfOpenProfile function. You then store and retrieve information from the file 
by using functions such as PrfQueryProfileString and PrfWriteProfileString. You 
can also create and manage groups and program lists by using functions such as 
PrfAddProgram and PrfCreateGroup. 


2.4.2.1. Creating or Opening an Initialization File 


You can create an initialization file or open an existing initialization file by using 
the PrfOpenProfile function. The function takes a handle to an anchor block 
and a pointer to the name of an initialization file. If the file doesn’t exist in | the 
given path, the function automatically creates an initialization file. 


The following example creates an initialization file named pmtools.ini in the 
current directory: 


HAB hab; 
HINI hini; 


hab = WinInitialize (0); 
if ((hini = PrfOpenProfile(hab, "pmtools.ini")) == NULL) 
/7* initialization file not opened or created */ 


If it is successful, the PrfOpenProfile function returns a handle to the initializa- 
tion file. Otherwise, it returns NULL. Once you have an initialization-file han- 
dle, you can create new sections in the file and make new settings. 


To close an initialization file, you use the PrfCloseProfile function. 
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2.4.2.2 Reading and Writing Settings 


You can read and write strings, integers, and binary data to and from an initiali- 
zation file. To read from or write to an initialization file, you must provide a sec- 
tion and a key name that specifies which setting to read or to change. When writ- 
ing, if there is no corresponding section and/or key name, the section and/or 
key name is added to the file and assigned the given value. 


The following example creates the section “MyApp” and the key name 
“Main WindowColor” in a previously opened initialization file and assigns the 
value of the RGB structure to the new setting: 


HINI hini; 
RGB rgb = { Oxff, Ox00, Ox0O }; 


PrfWriteProfileData(hini, "MyApp", "MainWindowColor", &rgb, sizeof (RGB) ); 


To read a setting, you can retrieve the size of the setting and then read the 
setting into an appropriate buffer by using the PrfQueryProfileSize and 
PrfQueryProfileData functions, as shown in the following example. This example 
reads the setting “MainWindowColor” from the “MyApp” section only if the size 
of the data is equal to the size of the RGB structure. 

HINI hini; 


ULONG cb; 
RGB rgb; 


PrfQueryProfileSize(hini, "MyApp", "MainWindowColor", &cb); 


if (cb==sizeof (RGB) ) 
PrfQueryProfileData(hini, "MyApp", "MainWindowColor", G&rgb, &cb); 


You can also read strings by using the PrfQueryProfileString function and write 
strings by using the PrfWriteProfileString function. You can read integers 
(stored as strings) by using the PrfQueryProfileInt function. 


2.4.2.3 Identifying the Initialization Files 


You can retrieve the names of the MS OS/2 initialization files by using the 
PrfQueryProfile function. Although the MS OS/2 initialization files are usually 
named o0s2.ini and os2sys.ini, a user can use other files when starting the system. 


The following example retrieves the names of the MS OS/2 initialization files 
and copies the names of the initialization files to the arrays szUserName and 
szSysName. Once you know the names of the MS OS/2 initialization files, you 
can use that name to open the files and read settings. 

char szUserName [80]; 


char szSysName[80]; 
PRFPROFILE prfpro = { 80, (PSZ) szUserName, 80, (PSZ) szSysName }; 


PrfQueryProfile(hini, &prfpro); 


You can change the MS OS/2 initialization files to files of your choice by using 
the PrfReset function. This function takes the names of two initialization files 
and uses them as replacements for the os2.ini and os2sys.ini files. The system is 
then reset using the settings in the new files. 


2.4.2.4 Creating Groups and Program Lists 


You can create a group and a list of programs by using the PrfCreateGroup and 
PrfAddProgram functions. A group is a window, managed by Desktop Manager, 
that contains a list of programs. The user can start a program in the list by 
selecting the program title or double-clicking the title using the mouse. 
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The following example creates a new group, named “My Application,” and adds 
one program to it: 
HPROGRAM hGroup; 


HPROGRAM hProg; 
PROGDETAILS pprogde; 


progde.Length = sizeof (PROGDETAILS) ; 

progde.progt.proge = PROG_PM; /* Prof. Mngr. prog. */ 
progde.progt.fbVisible = SHE_VISIBLE; /* visible */ 
progde.pszTitle = "My Application"; /* program title a/ 
progde.pszExecutable = "c:\os2\myapp.exe" /* path to exe file */ 
progde.pszStartupDir = "o:\os2"; * work directory s/ 
progde.pszIcon = as /* empty if not used */ 
progde.pszEnvironment = aes 

progde.pszParameters = ee 

progde.swpInitial.fs = O; 

progde.swpInitial.cx = 0; 

progde.swpInitial.cy = 0; 


progde.swpInitial.x = 0; 
progde.swpInitial.y = O; 
progde.swpInitial.hwndInsertBehind = NULL; 
progde.swpInitial.hwnd = NULL; 


hGroup = PrfCreateGroup(HINI_LUSER, "My Application", SHE_VISIBLE) ; 
hProg = PrfAddProgram(HINI_USER, &progde, hGroup) ; 
2.4.3 Summary 


Profile Manager functions open and modify the MS OS/2 initialization files. Note 
that these functions are new with MS OS/2, version 1.2, and replace the Win 
initialization-file functions in previous versions of MS OS/2. 


PrfAddProgram Adds a program title to Desktop Manager. 
PrfChangeProgram Replaces information in the program list. 
PrfCloseProfile Closes a profile file. 

PrfCreateGroup Creates a new program group in a program list. 
PrfDestroyGroup Removes a group from Desktop Manager. 
PrfOpenProfile Opens a profile file. 

PrfQueryDefinition Retrieves program information. 
PrfQueryProfile Retrieves profile filenames. 
PrfQueryProfileData Retrieves information from the profile file. 
PrfQueryProfileInt Retrieves an integer from the profile file. 


PrfQueryProfileSize Retrieves the size of data stored at a specified location in 
the profile file. 


PrfQueryProfileString Retrieves a string from the profile file. 
PrfQueryProgramCategory Retrieves the program type. 


PrfQueryProgramHandle Retrieves program handles that match the name of a 
specified executable file. 


PrfQueryProgramTitles Retrieves information about programs in a group. 
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PrfRemoveProgram Removes a program from Desktop Manager. 
PrfReset Resets Presentation Manager. 

PrfWriteProfileData Places binary data in the profile file. 
PrfWriteProfileString Places a string in the profile file. 


2.5 Help Manager 


This section describes how to use Help Manager in MS OS/2 to display help 
information about your application to the user. Before reading this section, you 
should be familiar with the Help Manager user interface, messages and message 
queues, and menus. 


Help Manager functions and messages replace the help messages and help 
hook described in the Microsoft Operating System/2 Programmer’s Reference, 
Volume 1. 


2.5.1 About Help Manager 


You use Help Manager to create help panels and to manage user requests for 
help. A help panel is one or more lines of text that describe some feature of the 
application. The help panels for an application are stored in compressed format 
in a help library. The help library is a separate disk file rather than a resource 
within in the application’s executable file. This makes it easy to update a help 
library or to replace it with international versions of help. 


The user requests help in one of three ways: by pressing the Fi key, by using the 
Help menu, or by clicking the Help button in a dialog box or message box. The 
application must provide the Help menu and Help buttons in the application, 
and it must identify a specific help panel for each command or button. When the 
user requests help, Help Manager displays a help window alongside the applica- 
tion window and fills the help window with the text of the corresponding help 
panel. The user can view additional help panels in the help window by using the . 
commands in this help window, or dismiss the help window and return to the 
application. 


While the user views help panels, Help Manager processes all user input, notify- 
ing the application of actions carried out for or requested by the user. For exam- 
ple, the user can search for, print, or copy help panels using commands from 
menus in the help window. Help Manager carries out these actions without assis- 
tance from the application. In some cases, Help Manager sends a message to the 
application window so that the application can determine what additional action 
to take. For example, if the user input results in an error, Help Manager sends 
an HM_ERROR message to the application. 


Help Manager supports hypertext fields—words or phrases in one help panel that 
refer to other help panels. The user directs Help Manager to display the other 
help panels by choosing the hypertext field (using either the mouse or keyboard). 
Hypertext fields can also direct Help Manager to display help panels from other 
help libraries and even to start other programs. For example, a hypertext field 
can direct Help Manager to send a message to the application window to start 
the application tutorial. = 
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You create help libraries by using the Information Presentation Facility Compiler 
(IPFC). This compiler produces the compressed help library from the text files 
that contain your help text. The help text consists of actual text and embedded 
information tags. The information tags direct the compiler to carry out specific 
actions, such as setting the help-panel name and ID, setting the font and/or 
color of the text, displaying text in special formats such as lists or tables, adding 
a bitmap to the panel, and including help text from another file. For more infor- 
mation about the Information Presentation Facility Compiler, you must use 
QuickHelp, the display program for Microsoft documentation databases, 
described in Microsoft Operating System/2 Getting Started. The Information 
Presentation Facility Compiler is available only in the Microsoft OS/2 Presenta- 
tion Manager Toolkit, version 1.2. 


2.5.2 Using Help Manager in Applications 


In an application, a user should have three ways to access help: by pressing the 
F1 key, by choosing commands from the Help menu, and by clicking a Help but- 
ton. Help Manager provides support for all three methods. The following sec- 
tions explain how to enable this support for your application. 


2.5.2.1 Creating a Help Instance 


An application can create an instance of Help Manager by using the Win- 
CreateHelpInstance function. This function installs a help hook, initializes Help 
Manager for help processing, and returns a help-instance window handle. The 
application uses the help-instance window handle to direct Help Manager to 
carry out requests for help. 


To create a help instance, the application first fills a HELPINIT structure with 
information about the help table, the title of the help window, and the help 
library for the help instance. In the following example, the helpinit parameter is 
the HELPINIT structure. The hab parameter is the anchor-block handle of the 
application, returned by the WinInitialize function. 

HAB hab; 


HWND hwndHelp; 
HELPINIT helpinit = { 


sizeof (HELPINIT), /7* count of bytes in structure */ 
OL, /* return value from Help Mngr. */ 
NULL, /* pointer to tutorial name a/ 
MAKELONG (MY_RESOURCES, OxFFFF) 7* resource ID for help table */ 
NULL, /* handle to help table */ 
NULL, /* handle to replacement menu a/ 
Oo, /* replacement accelerator ID a/ 
O, /* replacement menu ID a/ 
"My Help!", /* help-window title a/ 
CMIC_HIDE_PANEL_ID, /* display help title only */ 
"c:\os2\help\myhelp.hlp" /* path to help library */ 


‘ 


hwndHelp = WinCreateHelpInstance(hab, &helpinit) ; 


The application must associate the help instance with a window by using the 
WinAssociateHelpInstance function. This association tells Help Manager which 
help instance to use when the user requests help in the window or in any of that 
window’s child or owned windows. A help instance can be associated with any 
frame window (that is, any window created with the WC_LFRAME class). The 
application always can retrieve the handle of the associated window for a help 
instance by using the WinQueryHelpInstance function. 
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The user requests help by pressing the F1 key, by choosing a command from the 
Help menu, or by clicking a Help button. These actions cause MS OS/2 to send 
a WM_HELP message to an application window procedure. To enable Help 
Manager to process the message and display help, the window procedure should 
pass the WM_HELP message to the WinDefWindowProc or WinDefDlgProc 
function. Although most window procedures immediately pass the WM_HELP 
message to the WinDefWindowProc or WinDefDlgProc function, a window pro- 
cedure can carry out some processing of the WM_HELP message before it 
passes the message, as shown in the following example. In all cases, however, 
the window procedure must return the value returned by WinDefWindowProc or 
WinDefDlgProc. 


case ‘WM_HELP : 
'  /* Preprocess the message here. */ 
return (WinDefWindowProc(hwnd, msg, mpi, mp2)); 


2.5.2.2 Creating a Help Table 


A help table is a list of window IDs and corresponding help-panel IDs. For each 
help request, Help Manager uses a help table to translate into a panel ID the 
window ID given with the request for help. Every help instance must have a help 
table. . 


The application must create the help table and associate the help table with the 
help instance. An application creates a help table by defining it in a resource 
script file or by initializing a HELPTABLE structure. Most applications define 
the help table in the resource script file, using the HELPTABLE and HELP- 
SUBTABLE statements as follows: 


HELPSUBTABLE MY_MAIN_WINDOW_HELP 
BEGIN 


HELPSUBITEM IDM_HELPFORHELP, IDH_FORHELP 
HELPSUBITEM IDM_EXTENDEDHELP, IDH_FOREXTENDED 


HELPSUBITEM IDM_KEYSHELP, IDH_KEYS 
HELPSUBITEM IDM _HELPINDEX, IDH_INDEX 
HELPSUBITEM IDM_ABOUT, IDH_ABOUT 


END 
HELPSUBTABLE MY_DIALOG_HELP 
BEGIN 


HELPSUBITEM MY_DIALOG, IDH_DLG_EXTENDED 
HELPSUBITEM MY_DIALOG_EDIT, IDH_DLG_EDIT 
END ; 


HELPTABLE MY_MAIN_WINDOW 
BEGIN 


HELPITEM MY_MAIN_WINDOW, MY MAIN _WINDOW_HELP, IDH EXTENDED 
HELPITEM MY_DIALOG, MY_DIALOG_HELP, IDH_DLG_EXTENDED 
END 


In the preceding example, the HELPTABLE statement defines the help table. It 
specifies help for two windows: the main window and a dialog window. (The 
MY_MAIN_WINDOW and MY_DIALOG constants, defined elsewhere, must 
be unique and must be equal to the window IDs for these given windows.) 


The HELPITEM statements within the HELPTABLE statement identify the main 
and dialog windows and the help subtables that apply to them. A help subtable 
specifies the help-panel ID that corresponds to a window ID. The HELPITEM 
statements also specify the help-panel ID for the extended help associated 

with each window. For example, the dialog window has the help subtable 
MY_DIALOG_HELP and the extended help panel IDH_DLG_EXTENDED 
(the MY_DIALOG_HELP and IDH_DLG_EXTENDED constants must be 
defined elsewhere). 
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The HELPSUBTABLE statements define the window IDs and corresponding 
help-panel IDs for each child window of the specified main or dialog window. 


After receiving a help request, Help Manager determines which window is active 
and uses the ID of the active window to select a help subtable. Help Manager 
then determines the ID of the window that has the input focus (if any) and uses 
the ID of the focus window with the selected help subtable to identify the help 
panel. After Help Manager identifies the help panel, it displays the help panel in 
the help window. Help Manager positions the help window next to the “relative” 
window (the relative window is the window next to which the system displays the 
help window). The relative window is usually the active window, but it can be set 
to another window by using the HM_SET_ACTIVE_WINDOW message. 


2.5.2.3 Creating a Help Library 


You create a help library by using a text editor to create a help text file and then 
compiling the help text file with the Information Presentation Facility Compiler 
(IPFC). The help library must contain one or more help panels, each with a 
unique panel ID or name. In the help text file, each help panel must start with 
the :h1 tag. The help text file itself must start with the :userdoc. tag and end 
with the :euserdoc. tag. The following help text file contains two help panels: 
:userdoc. 
:hl res=1.Extended Help 
Display this help when the user requests extended help. 
:hl res=2.Other Help. 


Display this help when the user requests any other help. 
:euserdoc. 


The res= option with the :h1 tag identifies the panel ID for the help panel. The 
text immediately following the :h1 tag specifies the title of the panel. For exam- 
ple, “Extended Help” is the title of the first panel and “Other Help” is the title 
of the second. All subsequent text, up to the next :h1 tag, belongs to that help 
panel. 


2.5.2.4 Using the F1 Key 


The F1 key is the system Help key. Help Manager automatically enables this key 
for a window whenever an application creates a help instance and associates it 
with the frame window. The user can display help for specific items in the win- 
dow, such as menu commands, by selecting the item and pressing the F1 key. 
Whenever the user presses the F1 key, Help Manager retrieves the ID of the 
selected item and uses the ID to locate the corresponding help-panel ID. If Help 
Manager finds a help-panel ID, it displays that help panel. Otherwise, it displays 
the extended help panel. 


Although Help Manager carries out all processing for the Fi key, the application 
must provide appropriate help-table entries for each item that can be selected. If 
the active window is not directly associated with a help instance, Help Manager 
checks the window’s parent and owner windows until it finds an "associated help 
instance. It first checks the parent window, the parent window of the parent win- 
dow, and so on, until it finds a window that has an associated help instance. 
Help Manager checks the owner window only if the parent-window check ended 
at the desktop and no help instance was found. 
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2.5.2.5 Using the Help Menu 


The Help menu lets the user view general help for an application. The menu 
appears as the last (rightmost) menu in the menu bar and contains the following 
commands: 


Command Description 


Help for Help Displays general information about 
help and how to access help. 


Extended Help Displays information about the appli- 
cation window. This help information 
can explain the fields in the window, 
the window’s purpose, and how the 
user should interact with the window. 


Keys Help Displays a list of the function keys 
used by the application. 


Help index Displays an alphabetical list of all the 
help-index entries for the application. 
The author of the help text source file 
creates the help index by including 
index tags within the help file. 


About Displays copyright information for the 
application. The About command is 
used only in the Help menu for the 
application window. 


The application must create the Help menu, add it to the menu bar, and process 
the menu commands. The most convenient way to create the Help menu and 
add it to the menu bar is to place the following statements in the application’s 
MENU statement in the resource script file: 


SUBMENU "“Help", 1 


BEGIN ; 
MENUITEM "“Help for Help...", IDM_HELPFORHELP 
MENUITEM "“Extended Help...", IDM_EXTENDEDHELP 
MENUITEM ““Keys Help...", IDM_KEYSHELP 
MENUITEM “Help “index...", IDM_HELPINDEX 
MENUITEM SEPARATOR 
MENUITEM "A*bout...", IDM_ABOUT 

END 


You can assign any values for the IDM_ constants (IDM_HELPFORHELP and 
IDM_EXTENDEDHELP, for example) as long as the values are unique within 
the menu. 


To process the menu commands, the window procedure for the application 

must process the WM_COMMAND message. The application receives a 
WM_COMMAND message whenever the user chooses one of the menu com- 
mands. For each Help-menu command, the application must send an appropri- 
ate help message to the help instance for the application, as shown in the follow- 
ing statements. 
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case WM_COMMAND: 
switch aercaceuenp ee { 
case IDM_HELPFORHE /* display help for help panel */ 
ingendha (husancin HM_DISPLAY_HELP, 
MPFROMSHORT (IDH_HELPFORHELP) , 
MPFROMSHORT (HM_RESOURCEID) ) ; 


break; 

case IDM_EXTENDEDHELP: /* display extended help a / 
WinSendMsg(hwndHelp, HM_EXT_ uenp. OL, OL); 
break; 

case IDM_ KEYSHELP : /* display keys help panel a/ 
WinSendMsg (hwndHelp, HM_KEYS_HELP, OL, OL); 
break; 

case IDM_HELPINDEX: /* display help index */ 
WinSendMsg(hwndHelp, HM_HELP_INDEX, OL, OL); 
break; ; 

case IDM_ABOUT: /* create about dialog box a/ 


WinDlgBox (HWND_DESKTOP, hwnd, MyAboutProc, 
NULL, MY_ABOUTBOX, NULL); 
break; 


return (OL); 


In the preceding statements, the HM_DISPLAY_HELP message directs Help 
Manager to display the specific help panel. You can identify the panel by 
using a panel ID or by using a panel name. In this example, the constant 
HM_RESOURCEID directs Help Manager to locate the panel using the panel 
ID, IDH_HELPFORHELP. 


The HM_EXT_HELP message directs Help Manager to display extended help 
for the help instance. The panel ID for extended help is specified in the help 
table of the help instance. When Help Manager receives HM_EXT_HELP, it 
uses the extended help-panel ID to locate and display extended help. 


The HM_KEYS_HELP message directs Help Manager to display the help panel 
that contains a description of the application keys. Although the application 
must supply the panel ID for keys help, the HM_KEYS_HELP message does 
not take parameters. Instead, whenever Help Manager receives this message, it 
sends the HM_QUERY_KEYS_HELP message back to the application. The 
application must return the keys-help panel ID as shown in the following state- 
ments: 


case HM_QUERY_KEYS_HELP: 
return (IDH_KEYSHELP) ; 


The HM_HELP_INDEX message directs Help Manager to display the help 
index for the help instance. Because the help index has no explicit panel ID, this 
is the only way to display the help index from the application. 


Although the About command is usually placed in the Help menu, Help 
Manager does not support the About command. The application can use the 
WinDIlgBox function to display a dialog box that contains copyright information 
in response to the user choosing the About command. A corresponding dialog 
template must be defined in the resource script file. 


2.5.2.6 Using Help Buttons 


Help buttons provide an alternative way to display contextual help for fields in 
dialog boxes. A Help button is a push button that displays help information 
when the user clicks it using the mouse. It usually appears in the lower-right part 
of a dialog box. Clicking a Help button has the same effect as pressing the F1 key 
(that is, it displays information about the selected field). 
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The application must add Help buttons to dialog boxes, but Help Manager car- 
ries out the processing. The most convenient way to add a Help button to a dia- 
log box is to use a PUSHBUTTON statement in the dialog template in the 
resource script file. The following statements define a very simple dialog box 
with a Help button: 


DLGTEMPLATE MY_DIALOG 
BEGIN 


DIALOG "My Dialog!", MY_DIALOG, 0,0, 200,85,,FCE_TITLEBAR 
BEGIN 

LTEXT "Enter name:", MY LABEL, 10,40, 60,15 

ENTRYFIELD "", MY_DIALOG_EDIT, 70,40, 120,15, ES MARGIN 


DEFPUSHBUTTON "OK", MY_OK, 10,10, 60,15 
PUSHBUTTON "“Help", MY_HELP, 110,10, 60,15, 
BS_NOPOINTEREOCUS | BS_HELP 
END 
END 


The Help button must have the BS_HELP and BS_NOPOINTERFOCUS styles. 
When the button has the BS_HELP style, the system interprets a button click as 
a request for help. When the button has the BS_NOPOINTERFOCUS style, the 
input focus does not move from the Help button when it is clicked; this allows 
Help Manager to determine which field in the dialog box is selected. 


2.5.2.7 Destroying a Help Instance 


When a help instance is no longer needed, you can destroy it by using the Win- 
DestroyHelpInstance function. This function closes the help-instance window 
and removes the corresponding help hook. Before destroying the help instance, 
you should disassociate the help instance from the window by using the Win- 
AssociateHelpInstance function and specifying a NULL window handle. After a 
help instance is disassociated, it can be destroyed. 


2.5.2.8 Handling Errors 


Help Manager functions typically indicate errors by returning FALSE. If a func- 
tion is unsuccessful, the application can use the WinGetLastError function to 
retrieve the value of the error. 


If the user is viewing a help panel when an error occurs, Help Manager sends 
the HM_ERROR message to the active application window to notify the applica- 
tion of the error. Help Manager does not display error messages to the user; the 
application must display its own messages. 


2.5.3 Help Hooks and Help Manager 


Help Manager installs a help hook when the application creates the Help 
Manager instance. This hook enables Help Manager to trap user requests for 
help. When using Help Manager for your application, it is recommended that 
you do not install your own help hooks. If you choose to do so, however, you 
must install the help hook prior to creating the help instance because the Help 
Manager help-hook procedure always returns TRUE, preventing all subsequent 
hook procedures from being called. If you do install a help hook, it must return 
FALSE so that Help Manager can process requests for help. 
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2.5.4 Summary 
The following MS OS/2 functions and messages work with Help Manager. 
2.5.4.1 Functions 
MS OS/2 provides the following help functions: 
WinAssociateHelpInstance Associates a help instance with a given window. 
WinCreateHelpInstance Creates a help instance. 
WinCreateHelpTable Identifies or changes the pointer to the help table. 
WinDestroyHelpInstance Destroys an instance of Help Manager. 


WinLoadHelpTable Identifies or changes the handle of the module that con- 
tains the help-table resource and the ID of that resource. 


WinQueryHelpInstance Retrieves the handle of the help instance associated 
with the specified window. 


2.5.4.2 Messages Sent by Help Manager 
Help Manager sends the following messages to the application: 


HM_ACTIONBAR_COMMAND Sent to the application when the user 
chooses a command from an application-supplied menu. 


HM_ERROR Notifies the application of an error caused by a user action. 


HM_EXT_HELP_UNDEFINED Notifies the application that an extended help 
panel is not defined for the active window. 


HM_HELPSUBITEM_NOT_FOUND Sent to the application when the user 
requests help about a field and the system cannot find a related entry in the help 
subtable. 


HM_INFORM Notifies the application that the user has selected a hypertext 
field in the help window. The hypertext field must have been created using the 
sinform tag. 


HM_QUERY_KEYS_HELP Sent to the application when the user requests 
keys help. The application responds by returning the ID of the requested keys- 
help panel. 


HM_TUTORIAL Sent to the application when the user chooses the Tutorial 
command from a help panel. The application then calls its own tutorial program. 


2.5.4.3 er Sent to Help Manager 
The application sends the following messages to Help Manager: 


HM_CREATE_HELP_TABLE Specifies a new help table for the help 
instance. 


HM_DISMISS_WINDOW Directs Help Manager to close the help window 
associated with the last active window. 


HM_DISPLAY_HELP Directs Help Manager to display a specific help 
window. 
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HM_EXT_HELP Directs Help Manager to display the extended help panel for 
the active application window. 


HM_HELP_CONTENTS Directs Help Manager to display the table of con- 
tents for the open help library. 


HM_HELP_INDEX Directs Help Manager to display the index for the open 
help library. 


HM_KEYS_HELP Directs Help Manager to display the help panel that con- 
tains information about the application keys. 


HM_LOAD_HELP_TABLE Directs Help Manager to replace the existing help 
table with a help-table resource. 


HM_REPLACE_HELP_FOR_HELP Directs Help Manager to display the 
application-defined help panel instead of the general help panel that is shipped 
with Help Manager. 


HM_SET_ACTIVE_WINDOW Directs Help Manager to change the active 
window. Subsequent help messages are sent to the new active window and 
appear next to it. 


HM_SET_HELP_LIBRARY_NAME Identifies the help library to the help 
instance. 


HM_SET_HELP_WINDOW_LTITLE Sets the title text of a help window. 


HM_SET_SHOW_PANEL_ID Directs Help Manager to display, hide, or tog- 
gle the panel ID for each help panel displayed. 


2.6 Combination-Box Controls 


This section describes how to use combination-box controls to let the user 
choose and edit items from a list. Before reading this section, you should be 
familiar with entry-field controls, list-box controls, messages and message 
queues, and standard user-interface guidelines. 


Combination-box controls, also called combo boxes, are a new feature of MS 
OS/2, version 1.2. They can be used in addition to entry-field controls, which 
are described in the Microsoft Operating System/2 Programmer’s Reference, 
Volume 1. 


2.6.1 About Combo Boxes 


A combo box is two controls in one: an entry field and a list box. Combo boxes 
let the user enter data by typing in the entry field or by choosing from a list in 
the list box. 


A combo box automatically manages the interaction between the entry field and 

the list box. For example, when the user chooses an item in the list box, the 

combo box displays the text for that item in the entry field. The user can then 

edit the text without affecting the item in the list box. When the user types a 

letter in the entry field, the combo box scrolls the list box contents so that items 
. beginning with that letter become visible. 
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A combo box can have one of the following styles: 
Style Meaning 


CBS_SIMPLE A simple combo box. A simple combo box 
always displays its list box. The user can 
enter and edit text in the entry field or 
choose items from the list box. 


CBS_DROPDOWN A drop-down combo box. A simple drop- 
down combo box displays its list box only if 
the user clicks the drop-down icon at the 
right end of the entry field. It hides the list 
box when the user clicks the icon a second 
time. In a drop-down combo box, the user 

. Can enter and edit text in the entry field or 
choose items from the list box. 


CBS_DROPDOWNILIST _ A drop-down-list combo box is similar to 
the drop-down combo box, but the user can 
choose items only from the list box. The 
user cannot enter or edit text in the entry 
field. 


For combo boxes that have the CBS_DROPDOWN or CBS_DROPDOWNLIST 
styles, an application can show the list by using the CBM_SHOWLIST message. 
An application can determine whether the list is already showing by using the 
CBM_ISLISTSHOWING message. 


Applications can use any of the entry-field (EM_) and list-box (LM_) messages 
with combo boxes. Entry-field messages affect the entry field; list-box messages 
affect the list box. For example, an application can use the LM_INSERTITEM 
message to insert items into the list box. For more information on the entry-field 
and list-box messages, see the Microsoft Operating System/2 Programmer’s Refer- 
ence, Volume 1 and Volume 2. 


A combo box sends a variety of notification messages to its parent window. 

These notification messages are similar to the notification messages sent by 

entry-field and list-box controls. For example, the combo box sends a 

CBN_EFCHANGE notification message when the user changes text in the entry 

aoe and sends a CBN_LBSELECT when the user chooses an item in the list 
Ox. 


2.6.2 Using Combo Boxes 


You can create a combo box by using the WinCreateWindow function or by 
specifying a COMBOBOX statement in a dialog-window template in a resource 
file. When creating a combo box by using WinCreateWindow, you must 

specify the WC_COMBOBO%xX class, the predefined class for a combo box. If 
you do not specify a style, the default styles WS_GROUP, WS_TABSTOP, and 
WS_VISIBLE are used. 
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2.6.3 Summary 


The following MS OS/2 styles and messages are used with combination-box 


controls. 


2.6.3.1 Combo-Box Styles 


The following style constants, specified when the combo box is created, deter- 


mine its action and appearance: 


CBS_SIMPLE Specifies a simple combo box made up of a list-box control and 
an entry-field control that are visible at all times. 


CBS_DROPDOWN Specifies a drop-down combo box made up of an entry- 
field control and a button. When the user selects the button, a list-box control 


appears. 


CBS_DROPDOWNLIST Similar to a ateone -down combo box, but the user can- 
not enter or edit text in the entry field. 


2.6.3.2 Messages Sent to a Combo Box 


An application sends these messages to a combo box: 

CBM_HILITE Sets drop-down button highlighting in a combo box. 
CBML_LISLISTSHOWING Determines if a list box is visible in a combo box. 
CBM_SHOWLIST Shows or hides the list box in a combo box. 


2.6.3.3 Messages Sent by a Combo Box 


Messages sent from a combo box to an owner window notify the owner of events 
in the combo box, such as when the user edits text. A combo box sends the fol- 
lowing message to an owner window: 


WM_CONTROL Sent to the owner window of the combo box when a user 
event occurs in the combo box. This message contains one of the following 
notification control codes, specifying what event occurred. 


Code 


CBN_EFCHANGE 
CBN_EFSCROLL 


CBN_ENTER 
CBN_LBSCROLL 
CBN_LBSELECT 
CBN_MEMERROR 


CBN_SHOWLIST 


Description 


Indicates text in a combo-box entry field has 
changed. 


Indicates a combo-box entry field is 
scrolled. 


Indicates a combo-box item is selected. 
Indicates a combo-box list is scrolled. 
Indicates a combo-box list item is selected. 


Indicates the combo box cannot allocate 
sufficient memory. 


Indicates a combo-box list has dropped. 
down (is visible). 
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2.7 Multiple-Line Entry Fields 


This section describes how to use multiple-line entry fields to let the user view 
and edit text in an application. Before reading this section, you should be fami- 
liar with entry-field controls, messages and message queues, and standard user- 
interface guidelines. 


Multiple-line entry fields are a new feature of MS OS/2, version 1.2, and can be 
used in addition to entry-field controls, which are described in the Microsoft 
Operating System/2 Programmer’s Reference, Volume 1. 


2.7.1 About Multiple-Line Entry Fields 


A multiple-line entry field (MLE) is a very sophisticated control window that 
users use to view and edit multiple lines of text. An MLE provides all the text- 
editing capability of a simple text editor, making these features readily available 
to applications. 


You can create multiple-line entry fields by using the WinCreateWindow func- 
tion or by specifying the MLE statement in a dialog-window template in a 
resource file. 


2.7.1.1 Editing MLE Text 


An MLE contains one or more lines of text. Each line consists of one or more 
characters and ends with one or more characters that represent the end of the | 
line. The user inserts text by typing (when the MLE has the focus). The applica- 
tion can insert text at any time by using the MLM_INSERT message and specify- 
ing the text as a null-terminated string. The MLE inserts the new text at the cur- 
sor position or replaces the selected text. 


The entry mode determines the action of the MLE when the user inserts text. 
The entry mode can be set to overstrike or insertion. The user sets it by pressing 
the INSERT key. When overstrike mode is enabled, at least one character is 
always selected. This means that the MLM_INSERT message always replaces at 
least one character. If insert mode is enabled, the MLM_INSERT message 
replaces only characters the user or the application has selected. Otherwise, the 
MLE makes room for the inserted characters by moving existing characters to 
the right at the cursor position. 


The cursor position, identified by a flashing caret, is always specified as a char- 
acter offset, relative to the beginning of text. The user sets the cursor position by 
moving the flashing caret using the mouse or the direction keys. An application 
can set the cursor position by using the MLM_SETSEL message. This message 
directs the MLE to move the flashing caret to a given character position. 


The MLM_SETSEL message also sets the selection. The selection is one or 
more characters of text on which the MLE carries out an operation, such as 
deleting or copying. The user selects text by pressing the SHIFT key while moving 
the cursor. An application selects text by specifying the cursor position and 
anchor point using the MLM_SETSEL message. The selection is all text between 
the cursor position and the anchor point. If the cursor position and anchor point 
are equal, there is no selection. An application can retrieve the cursor position 
and/or anchor point by using the MLM_QUERYSEL message. 
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The user can delete characters, one at a time, by pressing the DELETE key or the 
BACKSPACE key. These keys delete the character to the left of the cursor. An 
application can delete one or more characters by using the MLM_DELETE mes- 
sage. This message directs the MLE to delete a specified number of characters, 
starting at the given position. This message does not change the cursor position. 
An application can delete selected text by using the MLM_CLEAR message. 


An application can reverse the previous operation by using the MLM_UNDO 
message. This message directs the MLE to restore the entry field to its previous 
state. It is a quick way to fix users’ editing mistakes. 


But not all operations can be undone. The application can determine whether 
the previous operation can be undone by using the MLM_QUERYUNDO mes- 
sage. This message returns TRUE and an indication of the type of operation that 
can be undone. An application can prevent a subsequent MLM_UNDO message 
from changing the state of the MLE by using the MLM_RESETUNDO message. 


2.7.1.2 Formatting MLE Text 


An application can retrieve the number of lines of text in an MLE by using the 
MLM_QUERYLINECOUNT message. It can retrieve the number of characters 
in the MLE by using the MLM_QUERYTEXTLENGTH message. The amount 
of text and, subsequently, the number of lines to be entered in an MLE depend 
on the text limit. An application can set the text limit by using the 
MLM_SETTEXTLIMIT message and determine the current limit by using the 
MLM_QUERYTEXTLIMIT message. The user cannot set the limit. If the user 
types to the text limit, the MLE beeps and ignores subsequent characters. If the 
application attempts to add text beyond the limit, the MLE truncates the text. 


An application can control the length of each line in an MLE by enabling word- 
wrapping. When word-wrapping is enabled, the MLE automatically breaks any 
line that is longer than the MLE is wide. An application can set word-wrapping 
by using the MLM_SETWRAP message, and it can determine whether the MLE 
is wrapping text by using the MLM_QUERYWRAP message. Unless the 
MLS_WORDWRAP style is specified when the MLE is created, word-wrapping 
is initially disabled. 


An application can set tab stops for an MLE by using the MLM_SETTABSTOP 
message. Tab stops specify the maximum width of tab character. When the user 
or an application inserts a tab character, the MLE expands the character so 

that it fills the space between cursor position and the next tab stop. The 
MLM_SETTABSTOP message actually sets the distance (specified in pels) 
between tab stops, and the MLE provides as many tab stops as needed, no 
matter how long the line gets. An application can retrieve the distance between 
tab stops by using the MLM_QUERYTABSTOP message. 


An application can use the MLM_SETFORMATRECT message to set the for- 
mat rectangle. The format rectangle is used to set the horizontal and/or vertical 
limits for text. The MLE sends a notification message to the parent window of 
the MLE if text exceeds the limit. An application typically uses the format rect- 
angle to provide its own word-wrapping or other special text processing. An 
application can retrieve the current formatting rectangle by using the 
MLM_QUERYFORMATRECT message. 
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An application can prevent the user from entering text in the entry field by using 
the MLM_SETREADONLY message. The MLM_QUERYREADONLY mes- 
sage specifies whether the MLE is read-only. An application can also set the 
MLE to read-only by specifying the MLS_READONLY style when creating the 
MLE. 


An application can set the colors and font for an MLE by using the 
MLM_SETTEXTCOLOR, MLM_SETBACKCOLOR, and MLM_SETFONT 
messages. These messages affect all text in the MLE; an MLE cannot contain a 
mixture of fonts and colors. An application can retrieve the current values 

for the color and the font by using the MLM_QUERYTEXTCOLOR, 
MLM_QUERYBACKCOLOR, and MLM_QUERYFONT messages. 


2.7.1.3 Importing and Exporting MLE Text 


An application can copy text to and from an MLE by importing and exporting. 
Importing using the MLM_IMPORT message copies text from a buffer to the 
MLE. Exporting using the MLM_EXPORT message copies text from the MLE 
to a buffer. The application uses the MLM_SETIMPORTEXPORT message to 
set the import and export buffers. To import, the application must fill the buffer 
with the text to copy to the MLE. To export, the MLE copies the specified text 
to the buffer. 


An application can import and export text in a variety of formats. The text for- 
mat identifies which characters are used for the end-of-line characters and is set 
using the MLM_FORMAT message. An MLE can have the following text for- 


mats: 

Type Format 

MLFIE_CFTEXT Exported lines end with a carriage-return/ 
newline character pair (OxOD, O0x0A). 
Imported lines must end with a newline 
character, a carriage-return/newline charac- 
ter pair, or a newline/carriage-return char- 
acter pair. 

MLFIE_NOTRANS Imported and exported lines end with a 
newline character (Ox0A). 

MLFIE_WINFMT For exported lines, the carriage-return/ 


newline character pair marks a hard line 
break (a break entered by the user), and 
two carriage-return characters and a newline 
character (0x0D, 0x0D, 0x0A) mark a soft 
line break (a break inserted during word- 
wrapping, not entered by the user). For 
imported lines, soft line break characters 
are ignored. 


The text format can affect the number of characters in a selection. To ensure 
the export buffer is large enough to hold exported text, an application can 

send the MLM_QUERYFORMATLINELENGTH message and the 
MLM_QUERYFORMATTEXTLENGTHEL message to determine the number of 
bytes in text to be exported. 
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Each time an application inserts text in an MLE, the MLE automatically 
refreshes the display by drawing the new text. When an application copies large 
amounts of text to an MLE, refreshing can be quite time-consuming, so applica- 
tions should disable the automatic refresh setting in such cases. An application 
can disable this setting by sending the MLM_DISABLEREFRESH message. 
After copying all the text, the application can restore the refresh by sending the 
MLM_ENABLEREFRESH message. 


2.7.1.4 Copying and Pasting MLE Text 


The user can cut, copy, and paste text in an MLE by using the CTRL+DELETE, 
SHIFT+DELETE, and SHIFT+INSERT keys. An application can cut, copy, and paste 
text by using the MLM_CUT, MLM_COPY, and MLM_PASTE messages. The 
MLM_CUT and MLM_COPY messages direct the MLE to copy the selected 
text to the clipboard. The MLM_CUT message also deletes the text 
(MLM_COPY does not). The MLM_PASTE message directs the MLE to copy 
the text on the clipboard to the current position in the MLE, replacing any exist- 
ing text with the copied text. An application can delete the selected text without 
copying it to the clipboard by using the MLM_CLEAR message. 


An application can also copy the selected text from an MLE to a buffer by using 
the MLM_QUERYSELTEXT message. This message does not affect the con- 
tents of the clipboard. 


2.7.1.5 Searching and Replacing MLE Text 


An application can search for a specified string within MLE text by using the 
MLM_SEARCH message. This message directs the MLE to search for the’ 
string. If the string is found, the MLE returns TRUE. The cursor does not move 
to the string unless the message specifies the MLFSEARCH_SELECTMATCH 
option. 


An application can also use the MLM_SEARCH message to replace one string 
with another. If the MLFSEARCH_CHANGEALL option is specified, the 
MLE replaces all occurrences of the search string with the replacement 

string. Both the search string and the replacement string must be given in a 
MLE_SEARCHDATLA structure passed with the message. 


2.7.1.6 MLE Notification Codes 


An MLE sends notification codes to its parent window whenever certain events 
occur, for example, when the user or the application tries to insert too much 
text or when the user uses the scroll bars. The parent window uses the 
notification codes to carry out custom operations for the MLE or to respond to 
errors. Notification codes that are closely related to MLE messages are 
described here. 


The MLE sends the MLN_HSCROLL or MLN_VSCROLL notification codes 
when the user uses the scroll bars so the application can monitor the visible con- 
tents of the MLE. The application can also monitor the contents of an MLE by 
using the MLM_QUERYFIRSTCHAR message. This message identifies the 
character in the upper-left corner of the MLE (by specifying its offset). This 

_ represents the first MLE character that is visible to the user. An application can 
move a specified character to the upper-left corner of an MLE by using the 
Sa a ero ae message as an alternative way of scrolling the contents 
of an E. 
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The MLE sends an MLN_CHANGE notification code when the user changes 
the text in some way. This code is especially useful when the MLE is in a dialog 
box because it can determine whether the dialog procedure should process the 
contents of the MLE. The MLM_QUERYCHANGED message also can deter- 
mine whether the user has made changes. The MLM_SETCHANGED message 
causes the MLE to send a notification code, regardless of whether the user has 
changed anything; this code can also be used to hide a change made by a user. 


2.7.1.7 MLE Styles 


MLE styles can be specified by using the WinCreateWindow function or the 
MLE statement in a resource file. Styles can be combined by using the OR 
operator. Applications can specify a combination of the following styles for an 


MLE: 

Style Meaning 

MLS_BORDER Draws a border around the MLE. 

MLS_HSCROLL Adds a horizontal scroll bar to the MLE. 
The scroll bar is enabled when any line 
exceeds the width of the MLE. 

MLS_IGNORETAB Directs the MLE to ignore the TAB key. 

MLS_READONLY Prevents the MLE from accepting text from 
the user. This style is useful for displaying 
lengthy static text in windows or dialog 
boxes. 

MLS_VSCROLL Adds a vertical scroll bar to the MLE. The 


scroll bar is enabled when the number of 
lines exceeds the height of the MLE. 


MLS_WORDWRAP Prevents lines that are longer than the width 
of the MLE. The MLE automatically breaks 
the line at a convenient place. 


2.7.2 Using Multiple-Line Entry Fields 


You can create an MLE by using the WinCreateWindow function or by specify- 
ing the MLE statement in a dialog-window template in a resource file. The fol- 
lowing example shows how to create an MLE using WinCreateWindow: | 


HWND hwndParent; /* parent-window handle */ 
HWND hwndMLE; /* MLE handle a/ 


hwndMLE = WinCreateWindow (hwndParent, 
WC_MLE, 


"Test" , 
MLS_BORDER | WS_VISIBLE, 
100, 100, 100, 100 
hwndParent, 

HWND_TOP, 

2, NULL, NULL); 


An MLE has the WC_MLE window class. As with other controls created using 
the WinCreateWindow function, the WS_VISIBLE style must be set to display 
the window immediately. 
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It is more common to create an MLE by using an MLE statement in a dialog- 


window template in a resource file, as shown in the following example: 
MLE "", 101, 110, 10, 50, 100 


The predefined class for an MLE is WC_MLE. If you do not specify a style, the 
default styles MLS_BORDER, WS_GROUP, and WS_TABSTOP are used. 


2.7.3 Summary 
The following MS OS/2 styles and messages are used with multiple-line entry 


fields. 


2.7.3.1 MLE Styles 


The following style constants, specified when the MLE is created, determine its 


action and appearance: 
MLS_BORDER Places a thin border around the MLE. 
MLS_HSCROLL Adds a horizontal scroll bar to the MLE. 


MLS_IGNORETAB Prevents the TAB key from functioning in the MLE. 
MLS_READONLY Makes the MLE text read-only. The user cannot enter or 


edit text in the MLE. . 
MLS_VSCROLL_ Adds a vertical scroll bar to the MLE. 


MLS_WORDWRAP_ Automatically moves words that do not fit at the end of a 


line to the next line. 


2.7.3.2 Messages Sent to an MLE 


An application sends the following messages to an MLE: 
MLM_CHARFROMLINE Returns the offset to a line, 
MLM_CLEAR Clears selected text in an MLE. 

MLM_COPY Copies selected text from an MLE to the clipboard. 
MLM_CUT Cuts selected text from an MLE to the clipboard. 
MLM_DELETE Deletes text from an MLE. 
MLM_DISABLEREFRESH Disables refresh for an MLE. 
MLM_ENABLEREFRESH Enables screen refresh for an MLE. 
MLM_EXPORT Exports text from an MLE. 

MLM_FORMAT Sets format for MLE import/export. 
MLM_IMPORT Imports text into an MLE. 

MLMLINSERT Inserts text into an MLE. 


MLM_LINEFROMCHAR Determines the line number of an MLE character. 


MLM_PASTE Copies the clipboard contents to an MLE. 


MLM_QUERYBACKCOLOR Retrieves the background color of an MLE. 
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MLM_QUERYCHANGED Determines if text in an MLE has changed. 
MLM_QUERYFIRSTCHAR Retrieves the offset of the first visible character. 
MLM_QUERYFONT Retrieves current MLE font information. 


MLM_QUERYFORMATLINELENGTH Retrieves the formatted MLE line 
length. 


MLM_QUERYFORMATRECT Retrieves the dimensions and mode of an 
MLE. 


MLM_QUERYFORMATTEXTLENGTH Retrieves the length of formatted 
MLE text. 


~ MLM_QUERYIMPORTEXPORT Retrieves values for the import/export 
buffer. 


MLM_QUERYLINECOUNT Retrieves the number of lines in an MLE. 
MLM_QUERYLINELENGTH Retrieves the length of an MLE line. 
MLM_QUERYREADONLY Determines MLE read-only mode. 
MLM_QUERYSEL Retrieves the selection position in an MLE. 
MLM_QUERYSELTEXT Retrieves selected text from an MLE. 
MLM_QUERYTABSTOP Retrieves the size of an MLE tab-stop. 
MLM_QUERYTEXTCOLOR Retrieves MLE text-color information. 
MLM_QUERYTEXTLENGTH Retrieves the length of MLE text. 
MLM_QUERYTEXTLIMIT Retrieves the text limit of an MLE. 
MLM_QUERYUNDO Determines if an MLE can undo an operation. 
MLM_QUERYWRAP Retrieves the state of word-wrap in an MLE. 
MLM_RESETUNDO Resets (clears) the MLE undo flag. 
MLM_SEARCH Searches an MLE. 

MLM_SETBACKCOLOR Sets the background color of an MLE. 
MLM_SETCHANGED Sets the MLE changed flag. 
MLM_SETFIRSTCHAR Sets the first visible character. 
MLM_SETFONT Sets MLE font information. 
MLM_SETFORMATRECT Sets the format rectangle and mode of an MLE. 
MLM_SETIMPORTEXPORT Sets the MLE import/export buffer. 
MLM_SETREADONLY Sets/clears the MLE read-only state. 
MLM_SETSEL Selects text within an MLE. 

MLM_SETTABSTOP Sets the size of an MLE tab-stop. 
MLM_SETTEXTCOLOR Sets the text color of an MLE. 
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MLM_SETTEXTLIMIT Sets the text limit for an MLE. 
MLM_SETWRAP. Sets/resets MLE word-wrap. 
MLM_UNDO_  Undoes an MLE operation. 


2.7.3.3 Messages Sent from an MLE 


Messages sent from an MLE to an owner window notify the owner of events in 
the MLE, such as when the user edits text. An MLE sends the ae mes- 


sage to an owner window: 


WM_CONTROL Sent to the owner window of the MLE when a user event 
occurs in the MLE. This message contains one of the following notification con- 
trol codes, specifying what event occurred. 


Code 


MLN_CHANGE 


Description 


i Indicates that text in an MLE has 


MLN_CLPBDFAIL 


MLN_HSCROLL 


MLN_KILLFOCUS 


MLN_MARGIN 


MLN_MEMERROR 


MLN_OVERFLOW 


MLN_PIXHORZOVERFLOW 
MLN_PIXVERTOVERFLOW 
MLN_SEARCHPAUSE 


MLN_SETFOCUS 


MLN_TEXTOVERFLOW 
MLN UNDOOVERFLOW 


MLN_VSCROLL 


changed. 


Indicates that a clipboard operation 
failed. 


Indicates a horizontal MLE scroll 
event. 


Indicates an MLE has lost the input 


focus. 


Indicates the mouse has moved over 
an MLE margin. 


Indicates insufficient memory available 
for an MLE. 


Indicates the MLE operation caused 
an overflow. 


Indicates an MLE horizontal overflow. 
Indicates an MLE vertical overflow. 


Determines the status of a search ini- 
tiated by an MLM_SEARCH message. 


Indicates the MLE receives the input 
focus. 


Indicates an MLE text-limit overflow. 


Indicates a text change cannot be 
undone. 


Indicates an MLE vertical scroll event. 
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3.1 Introduction 


This chapter describes MS OS/2 system functions and messages that are new or 


modified for MS OS/2, version 1.2. These functions provide features, such as 


multiple-line entry fields, extended attributes for disk files, and application help. 
The functions and messages represent distinct functional groups. 


3.1.1 Function Groups 


Programs use the function groups described in the following list to carry out 


specific tasks. 
Function group 


Dev 


Dos 


Gpi 


Kbd 


Usage 


Use the Presentation Manager device (Dey) func- 


tions to open and control Presentation Manager 
device drivers. These functions let you create 
device contexts that you can associate with a 
presentation space and use with the Gpi func- 


tions to carry out device-independent graphics for 


displays, printers, and plotters. 


Use the disk operating system (Dos) functions in 
full-screen and Presentation Manager sessions to 


read from and write to disk files, to allocate 


memory, to start threads and processes, to com- 


municate with other processes, and to access 


your computer’s devices directly. Most functions 


in this group can be used in Presentation 
Manager applications. 

Use the graphics programming interface (Gpi) 
functions to create graphics output for displays, 


printers, and other output devices. The Gpi func- 
tions give you a full range of graphics primitives, 


from lines to complex curves to bitmaps. You 
choose the attributes for the primitives, such as 
color, line width, and pattern, and then draw 
lines, text, and shapes. The retained-graphics 
capability lets you save the drawing in segments 


and build complex pictures by drawing a chain of 


segments. 
Use the keyboard (Kbd) functions in full-screen 


sessions to read keystrokes from the keyboard, | 


to manage multiple logical keyboards, and to 
change code pages and translation tables. 
Because the Presentation Manager session pro- 
vides its own keyboard support, Kbd functions 


are not needed in Presentation Manager applica- 


tions. 
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Function group Usage 


Mou : Use the mouse (Mou) functions in full-screen 
sessions to read mouse input from the mouse- 
event queue, to set the mouse-pointer shape, and 
to manage the mouse for all processes in a ses- 
sion. As with the keyboard, the Presentation 
Manager session provides its own mouse support, 
so Mou functions are not needed in Presentation 
Manager applications. 


Pic Use the picture-file (Pic) functions when working 
with picture files, typically either metafiles or 
interchange files. 


Prf Use the Profile Manager (Prf) functions to open 
and modify the MS OS/2 initialization files, 
os2.ini and os2sys.ini. The Prf functions let you 
store application information in the initialization 
files, making that information available to other 
applications or to the application itself after it 
has been stopped and restarted. 


Vio Use the video input-and-output (Vio) functions in 
full-screen sessions to write characters and char- 
acter attributes to the screen, to create pop-up 
windows for messages, to change the video 
modes, and to access physical video memory. 
Vio functions can also be used in advanced 
video-input-and-output (AVIO) applications for 
the Presentation Manager session to write charac- 
ters and character attributes in a window. Most 
Presentation Manager applications, however, use 
the graphics programming interface (Gpi) to 
write text in a window. 


Win Use the window-manager (Win) functions to 
create and manage windows. Presentation 
Manager applications use windows as the main 
interface with the user. The Win functions let 
you create menus, scroll bars, and dialog win- 
dows that let the user choose commands and sup- 
ply input. Your application receives all mouse 
and keyboard input as messages from the mes- 
sage queue. The Win functions let you retrieve 
messages from the queue and dispatch them to 
the window the input is intended for. 


3.1.2 Message Groups 


MS OS/2 uses system-defined messages that control the operation of applica- 
tions. The messages are divided into groups according to the various types of 
windows that can interpret and process the messages. Applications use the mes- 
sage groups described in the following list to carry out specific tasks. 
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Message group 


Combination box 
Entry field 
Help Manager 


Multiple-line entry field 


Menus 
Scroll bar 
Title bar 


General 


3.2 Directory 


Usage 


Use the combo-box control messages 
(CBM_) to control combination boxes. 


Use the entry-field control messages (EM_) 
to control entry fields. 


Use the Help Manager messages (HM_) to 
direct Help Manager for your applications. 


Use the multiple-line entry-field messages 
(MLM_) to control multiple-line entry 
fields. 


Use the menu messages (MM_) to control 
menus and menu items. 


Use the scroll-bar messages (SBM_) to con- 
trol scroll bars and sliders. 


Use the title-bar messages (TBML_) to con- 
trol title bars. 


Use the general window messages (WM_) to 
control the operation of windows of any 
window class. For most general window 
messages, the system sends the message to 
the window procedure of the given window. 
These messages can represent input from 
the keyboard, mouse, or timer. Some mes- 
sages are requests from the system to the 
window procedure for information, or they 
are actions to be taken. Other messages 
contain information that the window pro- 
cedure can use or save for processing later. 


MS OS/2 uses general window messages 
when creating, destroying, moving, sizing, 
and activating windows. It also uses these 
messages for all input to the window, 
whether the input is from devices, such as 
the keyboard and mouse, or through other 
windows, such as dialogs and menus. 


The remainder of this chapter is a directory that gives complete syntax, purpose, 
and parameter descriptions for MS OS/2, version 1.2, functions and messages. 
The types, macros, and structures used by a function are given with the func- 
tion, and they are described more fully in Chapter 4, “Types, Macros, Struc- 
tures.” You will notice the word New, Change, or Correction on the right side of 
the line that contains the function or message name. This heading tells you 
whether that particular function or message is new to MS OS/2, version 1.2; 
changed, or updated, from MS OS/2, version 1.1; or contains a correction to an 
error that appeared in MS OS/2, version 1.1 documentation. 
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Some of the function and message descriptions in this chapter include examples. 
The examples show how to use the functions and messages to accomplish simple 
tasks. In nearly all cases, the examples are code fragments, not complete pro- 
grams. The code fragment is intended to show the context in which the function 
or message can be used, but often assumes that variables, structures, and con- 
stants used in the example have been defined and/or initialized. Also, a code 
fragment may use comments to represent a task instead of giving actual state- 
ments. 


Although the examples are not complete, you can still use them in your pro- 
grams if you take the following steps: 


Include the os2.h file in your program. 


Define the appropriate include constants for the functions, structures, 
and constants used in the example. 


Define and initialize all variables. . 
Replace comments that represent tasks with appropriate statements. 
Check return values for errors and take appropriate actions. 


3.3 Functions and Messages 


The following list, in alphabetical order, details the new, chaneed, and corrected 
functions and messages for MS OS/2, version 1.2. 


lH CBM.HILITE 


Parameters 


Return Value 


CBM_SHOWLIST 57 


New 
CBM_HILITE 
mpl = MPFROMSHORT((USHORT) fHilite) ; 7* highlight flag _* 
mp2 = OL; 7* not used, must be zero */ 


An application sends a CBM_HILITE message to set the highlighting state of 
the drop-down list button in a combination box that was created with the 
CBS_DROPDOWN or CBS_DROPDOWNLIST style. 


fHilite Low word of mp1. Specifies whether to highlight or remove highlighting 
from the drop-down list button. If this parameter is TRUE, the system highlights 
the button; if it is FALSE, the system removes the highlighting. 


The return value is TRUE if the state of the drop-down list button changes or 
FALSE if it does not. 


m™ CBM_ISLISTSHOWING New 
CBM_ISLISTSHOWING 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /7/* not used, must be zero */ 


Parameters 
Return Value 


An application sends a CBM_ISLISTSHOWING message to determine whether 
the list box in a combination box is currently displayed. 


This message does.not use any parameters. 


The return value is TRUE if the list box is displayed or FALSE if it is not. 


See Also CBM_SHOWLIST 
m CBM_SHOWLIST New 

CBM_SHOWLIST 
mpl = MPFROMSHORT((USHORT) fShow) ; /* show flag a/ 
mp2 = OL; /* not used, must be zero */ 
An application sends a CBM_SHOWLIST message to show or ae the list box 
in a combination box. 

Parameters fShow Low word of mp1. Specifies whether to show or hide the list box. If 


Return Value 


See Also 


this parameter is TRUE, the list box is shown; otherwise, it is hidden. 


The return value is TRUE if the state of the list box changes or FALSE if it 
does not change. 


CBML_ISLISTSHOWING 
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CBN_EFCHANGE . New 


WM_CONTROL 
id = (USHORT) SHORT1IFROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = CBN_EFCHANGE; ; 


The CBN_EFCHANGE notification message is sent when the text in a 
combination-box entry field changes. 


Parameters id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to CBN_LEFCHANGE. 

See Also WM_CONTROL 

CBN_EFSCROLL New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP {mp 1) : /* control-window ID */ 
usNotifyCode = CBN_EFSCROL 
The CBN_EFSCROLL notification message is sent when a combination-box 
entry field is scrolled. 

Parameters id Low word of mp1. Identifies the control window. 


Return Value 
See Also 


CBN_ENTER 


usNotifyCode High word of mp1. Set to CBN_EFSCROLL. 
An application should return zero if it processes this message. 


WM_CONTROL 


New 


Parameters 


Return Value 
See Also 


WM_CONTROL 
id = (USHORT) SHORT1IFROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = CBN_ENTER; 


The CBN_ENTER notification message is sent when the user presses the ENTER 
key or double-clicks a list item in a combination box. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to CBN_ENTER. 


An application should return zero if it processes this message. 


WM_CONTROL 


CBN_MEMERROR = 59 


m™ CBN_LBSCROLL New 
WM_CONTROL 
id = (USHORT) SHORTI1FROMMP (mp1) ; /* control-window ID */ 


Parameters 


Return Value 


usNotifyCode = CBN_LBSCROLL; 


The CBN_LBSCROLL notification message is sent when a combination-box list 
is scrolled. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to CBN_LBSCROLL. 


An application should return zero if it processes this message. 


Return Value 
See Also 


See Also WM_CONTROL 
m@ CBN_LBSELECT New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = CBN_LBSELECT; 
The CBN_LBSELECT notification message is sent when a combination-box list 
item is selected. 
Parameters id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to CBN_LBSELECT. 
Return Value An application should return zero if it processes this message. 
See Also WM_CONTROL 
@ CBN_MEMERROR- New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = CBN_MEMERROR; 
The CBN_MEMERROR notification message is sent when a combination-box 
cannot allocate the amount of memory necessary. 
Parameters id Low word of mp1. Identifies the control window. 


usNotifyCode High word of mp1. Set to CBN_-MEMERROR. 
An application should return zero if it processes this message. 


WM_CONTROL 


60 CBN_SHOWLIST 


CBN_SHOWLIST 7 New 


WM_.CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = CBN_SHOWLIST; 


The CBN_SHOWLIST notification message is sent when the combination-box 
list is shown (dropped down). 


Parameters id Low word of mp1. Identifies the control window. 
| usNotifyCode High word of mp1. Set to CBN.SHOWLIST. 


Return Value An application should return zero if it processes this message. 
See Also WM_CONTROL 


DevEscape Change 
LONG DevEscape( hdc, cmdCode, cbinData, pbinData, pcbOutData, pbOutData) 


HDC hde; /« device-context handle a/ 
LONG cmdCode; /»« escape function to perform «/ 
‘LONG cbinData; /» size of input buffer »/ 
PBYTE pbinData; /« pointer to input buffer »/ 
PLONG pcbOutData; /» pointer to buffer for bytes in output buffer »/ 
PBYTE pbOutData; /« pointer to output-data buffer »/ 


The DevEscape function allows applications to access facilities of a device not 
otherwise available through the API. Because calls to escape functions are gen- 
erally sent to the device driver, the device driver must be able to use them. 


Parameters hdc Identifies the device context. 


cmdCode _ Specifies the escape function to perform. The following escape 
functions are currently defined: 


DEVESC_ABORTDOC 
-DEVESC_BREAK_EXTRA 
DEVESC_CHAR_EXTRA 
DEVESC_DRAFTMODE 
DEVESC_ENDDOC 
DEVESC_FLUSHOUTPUT 
DEVESC_GETSCALINGFACTOR 
DEVESC_NEWFRAME 
DEVESC_NEXTBAND 
DEVESC_QUERYESCSUPPORT 
DEVESC._QUERYVIOCELLSIZES 
DEVESC_RAWDATA 
DEVESC_STARTDOC 


Return Value 


Errors 


Comments 


DevEscape 61 


Devices can define additional escape functions by using other cmdCode values in 
the following ranges: 


Range Meaning 

32768-40959 Not stored in a metafile and not recorded. 
40960-49151 Stored in a metafile only. 

49152-57343 Stored in a metafile and recorded. 
57344-65535 Recorded only. 


cbInData Specifies the number of bytes of data in the buffer pointed to by the 
pbInData parameter. 


pbInData Points to the buffer that contains the input data required for the 
escape function. 


pcebOutData Points to the buffer that receives the number of bytes of data in 
the buffer pointed by the pbOutData parameter. If data is returned in the pbOut- 
Data parameter, pcbOutData is updated to the number of bytes of data returned. 


pbOutData Points to the buffer that receives the output from the escape func- 
tion. If this parameter is NULL, no data is returned. 


The return value is DEV_OK if the function is successful, DEVESC_ERROR if 
an error occurs, orp DEVESC_NOTIMPLEMENTED if the escape function is 
not implemented for the specified code. 


You can use the WinGetLastError function to retrieve the error value, which 
may be one of the following values: 


PMERR_ESC_CODE_NOT_SUPPORTED 
PMERR_INV_ESCAPE_DATA 
PMERR_INV_HDC 
PMERR_INV_LENGTH_OR_COUNT 


The standard escape functions and the corresponding DevEscape parameters are 
listed in the following paragraphs. 


The DEVESC_BREAK_EXTRA escape defines extra width to add to the break 
character when that character is transmitted to the device specified by the hdc 
parameter. The extra width is used in aligning text. The GpiQueryFonts function 
can be used to determine the break character used in a specific font. 


For DEVESC_BREAK_EXTRA, the DevEscape parameters contain the follow- 
ing information: 
Parameter Description 


cbInData Specifies the number of bytes pointed to by the 
pbInData parameter. This parameter must be either 
zero (for no extra spacing) or 4 (for extra spacing). 


pbInData Points to the fixed-point number (FIXED) that 
specifies the amount of extra width (in world 
coordinate units) to add to the break character. 


pebOutData Not used; can be NULL. 
pbOutData Not used; can be zero. 
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Extra spacing is initialized to zero whenever a display context is opened. Any 
change made to the extra spacing remains in effect until either the display con- 
text is closed or a new change to the extra spacing is made. 


The DEVESC_CHAR_EXTRA escape defines extra width to add to all charac- 
ters when they are transmitted to the device specified by the hdc parameter. The 
extra width is used in aligning text. 


For DEVESC_CHAR_EXTRA, the DevEscape parameters contain the follow- 
ing information: 
Parameter Description 


cbInData Specifies the number of bytes pointed to by the 
pbInData parameter. This parameter must be either 
zero (for no extra spacing) or 4 (for extra spacing). 


pbInData Points to the fixed-point number (FIXED) that 
specifies the amount of extra width to be added. 

pcebOutData Not used; can be NULL. 

pbOutData Not used; can be zero. 


Extra spacing is initialized to zero whenever a display context is opened. Any 
change made to the extra spacing remains in effect until either the display con- 
text is closed or a new change to the extra spacing is made. 


The extra width added to the break character is the sum of the break-extra and 
character-extra amounts. Providing a width vector to GpiCharStringPos or Gpi- 
QueryCharStringPosAt operates in addition to the extra spacing feature. Extra 


spacing does not override kerning; extra spacing adjustments and kerning adjust- 


ments simply sum. 


Text drawn in a path is not affected by the extra spacing. This means that out- 
lined text and text used for a clipping region are displayed as if the extra spacing 
fields were set to zero. 


The DEVESC_QUERYESCSUPPORT escape determines whether the device 
driver has implemented a particular escape. The return value gives the result. 
This escape is not stored in a metafile or recorded. 


For DEVESC_QUERYESCSUPPORT, the DevEscape parameters contain the 
following information: 


Parameter Description 

cbInData Specifies the number of bytes pointed to by the 
pbInData parameter. 

pbInData Specifies the escape-code value of the escape function 
to be checked. 

pebOutData Not used; can be NULL. 


pbOutData Not used; can be zero. 
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The DEVESC_QUERYVIOCELLSIZES escape returns the cell sizes supported 
by the device identified by the hdc parameter. 


For DEVESC_QUERYVIOCELLSIZES, the DevEscape parameters contain 
the following information: 


Parameter Description 

cbInData Not used; can be zero. 

pbInData Not used; can be NULL. 

pcbOutData Points to the number of bytes of data pointed to by 


the pbOutData parameter. Upon return, this parame- 
ter contains to the number of bytes returned. 


pbOutData Points to the buffer that receives the output from 
this escape function. The output is returned in a 
VIOSIZECOUNT structure and an array of 
VIOFONTCELLSIZE structures. These structures 
have the following forms: 


typedef struct _VIOSIZECOUNT { 
LONG maxcount; 
LONG count; 
} VIOSIZECOUNT; 


typedef struct _VIOFONTCELLSIZE { 
LONG cx; 
LONG cy; 
} VIOFONTCELLSIZE; 


The number of VIOFONTCELLSIZE structures 
returned is dependent on the value of the count field 
of the VIOSIZECOUNT structure. 


For a full description, see Chapter 4, “Types, Macros, 
Structures.” 


The DEVESC_GETSCALINGFACTOR escape returns the scaling factors for 
the x and y axes of a printing device. For each scaling factor, an exponent of two 
is put in the pbOutData parameter. For example, the value 3 is used if the scal- 
ing factor is 8. Scaling factors are used by devices that cannot support graphics 
at the same resolution as the device resolution. 


For DEVESC_GETSCALINGFACTOR, the DevEseape parameters contain 
the following information: 


Parameter Description 

cbInData Not used; can be zero. 

pbInData Not used; can be NULL. 

pebOutData Points to the number of bytes of data pointed to by 


the pbOutData parameter. Upon return, this parame- 
ter contains the number of bytes returned. 


pbOutData Points to the buffer that receives the output from this 
escape. A structure is returned that specifies the scal- 
ing factors for the x and y axes. 
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The DEVESC_STARTDOC escape indicates the start of a new print job. All 
subsequent output to the device context, up to the next DEVESC_ENDDOC 
escape, is spooled under the same job. 


For DEVESC_STARTDOC, the DevEscape parameters contain the following 
information: 


Parameter ; Description 

cbInData Specifies the number of bytes pointed to by the 
pbInData parameter. 

pbInData Points to the null-terminated string that specifies the 
name of the document. 

pcebOutData Not used; can be NULL. 

pbOutData Not used; can be NULL. 


The DEVESC_ENDDOC escape ends a print job started by the 
DEVESC_STARTDOC escape. 


For DEVESC_ENDDOC, the DevEscape parameters contain the following 
information: 


Parameter Description 

cbInData Not used; can be zero. 

pbInData Not used; can be NULL. 

pebOutData Points to the buffer that specifies the number of char- 


acters in the string pointed to by the pbOutData 
parameter. This parameter should be NULL if the 
number of characters is zero. 


pbOutData Points to the unsigned 16-bit integer that specifies the 
job identifier if a spooler print job was created. 


The DEVESC_NEXTBAND escape allows an application to signal that it has 
finished writing to a “band,” or rectangle. The coordinates of the next band are 
returned. This escape is used by applications that perform handle banding (“for- 
printing”) themselves. 


For DEVESC_NEXTBAND, the DevEscape parameters contain the following 
information: 


Parameter Description 

cbInData Not used; can be zero. 

pbInData Not used; can be NULL. 

pebOutData Points to the number of bytes of data pointed to by 


the pbOutData parameter. Upon return, this parame- 
ter contains the number of bytes returned. 


pbOutData Points to the address of the buffer that receives the 
output from this escape. A structure is returned that 
specifies the device coordinates of the next band. 
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The DEVESC_ABORTDOC escape stops the current job, erasing every- 
thing written by the application to the device since the last call to the 
DEVESC_ENDDOC escape function. 


For DEVESC_ABORTDOC, the DevEscape parameters contain the following 
information: 


Parameter Description 

cbInData Not used; can be zero. 
pbInData Not used; can be NULL. 
pebOutData Not used; can be NULL. 
pbOutData Not used; can be NULL. 


The DEVESC_NEWFRAME escape allows an application to signal when it has 
finished writing to a page. This escape is typically used with a printer device to 
advance to a new page. Using this escape is similar to processing the GpiErase 
function for a screen device context. 


For DEVESC_NEWFRAME, the DevEscape parameters contain the following 
information: 


Parameter Description 

cbInData Not used; can be zero. 
pbInData Not used; can be NULL. 
pebOutData Not used; can be NULL. 
pbOutData Not used; can be NULL. 


The DEVESC_DRAFTMODE escape turns draft mode on or off. Turning draft 
mode on instructs the device driver to print faster and, if necessary, with lower 
quality. You can change the draft mode only at page boundaries—for example, 
after a DEVESC_NEWFRAME escape. 


For DEVESC_DRAFTMODE, the DevEscape parameters contain the following 
information: 


Parameter Description 
cbInData Specifies the number of bytes pointed to by the 
pbInData parameter. 


pbinData Points to the signed 16-bit integer that specifies the 
draft mode. This value is 1 if draft mode is on and 
zero if draft mode is off. 


pebOutData Not used; can be NULL. | 
pbOutData Not used; can be NULL. 


The DEVESC_FLUSHOUTPUT escape removes any output from the device 
buffer. 
For DEVESC_FLUSHOUTPUT, the DevEscape parameters contain the follow- 
ing information: 

Parameter Description 


cbInData Not used; can be zero. 
pbInData Not used; can be NULL. 
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PSZ pszName; 
ULONG flOptions; 


Parameter Description 
pebOutData Not used; can be NULL. 
pbOutData Not used; can be NULL. 


The DEVESC_RAWDATA escape allows an application to send data directly 
to a device driver. For example, in the case of a printer device driver, the data 
could be a printer data stream. 


If raw data is mixed with other data—for example, Gpi data—being sent to the 
same page of a device context, the results are unpredictable and depend upon 
the action taken by the Presentation Manager device driver, which, in this case, 
might ignore the GPI data completely. In general, you should send raw data 
either to a separate page, using the DEVESC_NEWFRAME escape to obtain a 
new page, or to a separate document, using the DEVESC_STARTDOC and 
DEVESC_ENDDOC escapes to create a new document. 


For DEVESC_RAWDATA, the DevEscape parameters contain the following 
information: 


Parameter Description 
cbInData Specifies the number of bytes pointed to by the 
, pbinData parameter. 
pbInData Points to the raw data. 
pebOutData Not used; can be NULL. 
pbOutData Not used; can be NULL. 
See Also GpiErase 
Changes The escape functions DEVESC_BREAK_EXTRA, DEVESC_CHAR_EXTRA, 
and DEVESC_QUERYVIOCELLSIZES have been added. 
The DEVESC_STARTDOC and DEVESC_ENDDOC escapes indicate the start 
and end of a print job. 
DevPostDeviceModes _ Correction 
LONG DevPostDeviceModes( hab, pbDriverData, pszDriverName, achDeviceName, pszName, flOptions) 
HAB hab; /» anchor-block handle »/ 
PDRIVDATA pbDriverData; /» pointer to buffer for data »/ 
PSZ pszDriverName; /« pointer to string for driver name +/ 
PSZ achDeviceName; /« pointer to device name »/ 


/« pointer to string for output device name »«/ 
/« specifies various options »/ 


The DevPostDeviceModes function causes a device driver to post a dialog box 
so the user can set options for the device (resolution, font cartridges, and so 
on). 


The application can call this function first with a NULL data pointer to find how 
much storage is needed for the data buffer. It then calls the function a second 


Parameters 


Return Value 
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time to have the buffer filled with data. You can then pass the returned data to 
the DevOpenDC function as the buffer data pointed to by the pbDriverData 
parameter. 


hab Identifies the anchor block. 


pbDriverData Points to the data buffer that receives device data defined by 
the driver. If this parameter is NULL, the function returns the required buffer 
size. The format of the data is the same as for the pbData parameter of the 
DevOpenDC function. 


pszDriverName Points to the null-terminated string that contains the name of 
the device driver. 


achDeviceName Points to the null-terminated string that identifies the partic- 
ular device (for example, its model number). This string must not exceed 32 
bytes. Valid names are defined by device drivers. 


pszName_ Points to the null-terminated string that contains the printer name. 


flOptions Specifies whether the function should display a dialog box that. 
allows the user to change job properties, display two dialog boxes that allow the 
user to change job and printer properties, or simply return the current job pro- 
perties. This parameter can be one of the following values: 


Value Meaning 


DPDMF_POSTJOBPROP Display a dialog box that allows the user 
to change job properties. The default 
values for this dialog box are taken from 
the PM_SPOOLER_DD section of the 
os2.ini file if the pstName parameter 
specifies a logical address. If pstName is 
NULL, the default values are taken from 
the pbDriverData parameter. 


DPDMF_CHANGEPROP Display two dialog boxes. The first dialog 
box allows the user to change job proper- 
ties; the second allows the user to change 
printer properties. The default values for 
these dialog boxes are taken from the 
PM_SPOOLER_DD section of the os2.ini 
file. The function returns the new values in 
the pbDriverData parameter. The pszName 
parameter cannot be NULL when this 
option is selected. 


DPDMF_QUERYJOBPROP Return the current job properties. 


The return value, if the pbDriverData parameter is NULL, is the size (in bytes) 
required for the data buffer, DPDM_NONE if there are no settable options, or 
DPDM_ERROBR if an error occurs. 


The return value, if pbDriverData is not NULL, is DEV_OK if the function is 
successful, DPDM_NONE if there is no device mode, or DPDM_ERROR if an 
error occurs. 
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Errors 


See Also 
Corrections 
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HDC hdc; 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_DEVICE_NAME 
PMERR_INV_DRIVER_DATA 
PMERR_INV_DRIVER_NAME 
PMERR_INV_LOGICAL_ADDRESS 


DevOpenDC 


The sixth parameter (flOptions) was omitted in the previous description of the 
function. 


Correction 
BOOL DevQueryCaps( hdc, /Startitem, citems, alltems) 
/« device-context handle a/ 
/« first item to be returned a/ 


LONG /Startitem; 
LONG clitems; 
PLONG alltems; 


Parameters 


Return Value 


Errors 


Comments 


/»« number of items to be returned »/ 
/x array for device characteristics »/ 


The DevQueryCaps function queries the characteristics of the specified device. 


hdc Identifies the device context. 

IStartitem Specifies the first item of information to be returned in the array. 
cItems Specifies the number of items to be returned in the array. 

alltems Points to an array of device characteristics, starting with the item 
specified by the /Startitem parameter. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HDC 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_QUERY_ELEMENT_NO 


The following are possible values for the alltems parameter: 


CAPS_FAMILY Specifies the device type. These values are the same as the 
values for the type parameter in the DevOpenDC function. 


CAPS_IO_CAPS Specifies the device input/output capability. The possible 
values are as follows: 


Value Meaning 
CAPS_IO_.DUMMY Dummy device 
CAPS_IO_SUPPORTS_OP Output 
CAPS_IO_SUPPORTS_IP Input 


CAPS_IO_SUPPORTS_IO Output and input 
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CAPS_TECHNOLOGY Specifies the technology. The possible values are as 
follows: 


Value Meaning 
CAPS_TECH_.UNKNOWN Unknown (for example, metafile) 
CAPS_TECH_VECTOR_PLOTTER Vector plotter 
CAPS_TECH_RASTER_DISPLAY Raster display 
CAPS_TECH_RASTER_PRINTER Raster printer 
CAPS_TECH_RASTER_CAMERA Raster camera 
CAPS_TECH_POSTSCRIPT PostScript printer 


CAPS_DRIVER_VERSION Specifies the device-driver version number. 


CAPS_HEIGHT Specifies the media depth (for a full-screen maximized win- 
dow on a display) in pels. (For a plotter, a pel is defined as the smallest possible 
displacement of the pen and can be smaller than a pen width.) 

CAPS_WIDTH Specifies the media width (for a full-screen, maximized window 
for displays) in pels. 

CAPS_HEIGHT_IN.CHARS Specifies the media depth (for a full-screen, 
maximized window for displays) in character rows, for Vio calls only. 


CAPS_WIDTH_IN_CHARS. Specifies the media width (for a full-screen, max- 
imized window for displays) in character columns, for Vio calls only. 


CAPS_VERTICAL_RESOLUTION Specifies the vertical resolution (in pels 
per meter) of the device. 


CAPS_HORIZONTAL_RESOLUTION Specifies the horizontal resolution (in 
pels per meter) of the device. 


CAPS_CHAR_HEIGHT Specifies the default height (in pels) of the character 
box. 3 


CAPS_CHAR_WIDTH Specifies the default width (in pels) of the character 
box. 


CAPS_SMALL_CHAR_HEIGHT Specifies the default height (in pels) of the 
small character box. This number is zero if there is only one size of the charac- 
ter box. 


CAPS_SMALL_CHAR_WIDTH Specifies the default width (in pels) of the: 
small character box. This number is zero if there is only one size of the charac- 
ter box. 


CAPS_COLORS Specifies the number of distinct colors supported at the same 
time, including reset (gray-scales count as distinct colors). If loadable color 
tables are supported, this is the number of entries in the device color table. For 
plotters, the value returned is the number of pens plus one (for the background). 


CAPS_MOUSE_BUTTONS Specifies the number of mouse or tablet buttons 
that are available. A returned value of zero indicates that there are no mouse or 
tablet buttons available. 
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CAPS_FOREGROUND_MIX_SUPPORT Specifies the foreground-mix sup- 
port. The possible values are as follows: 


Value Meaning 
CAPS_FM_OR OR 
CAPS_FM_OVERPAINT Overpaint 
CAPS_FM_XOR ~  XOR 
CAPS_FM_LEA VEALONE Leave alone 
CAPS_FM_AND AND 
CAPS_FM_GENERAL_BOOLEAN Mixes 7 through 17 


The value returned is the sum of the values appropriate to the mixes supported. 
A device capable of supporting the OR mix mode must, as a minimum, return 1 
+ 2+ 16 = 19, signifying support for the mandatory mix modes OR, overpaint, 
and “leave-alone.” Note that these numbers correspond to the decimal represen- 
tation of a bit string that is seven bits long, with each bit set to 1 if the appropri- 
ate mode is supported. 


CAPS_BACKGROUND_MIX_SUPPORT Specifies the background mix sup- 
port. The possible values are as follows: 


Value Meaning 
CAPS_BM_OR OR 
CAPS_BM_OVERPAINT Overpaint 
CAPS_BM_XOR XOR 
CAPS_.BM_LEA VEALONE Leave alone 


The value returned is the sum of the values appropriate to the mixes supported. 
A device must, as a minimum, return 2 + 16 = 18 signifying support for the man- 
datory background mixes overpaint and leave alone. Note that these numbers 
correspond to the decimal representation of a bit string that is five bits long, 
with each bit set to 1 if the appropriate mode is supported. 


CAPS_LOADABLE_SYMBOL_SETS Specifies the number of fonts that may 
be loaded for Vio. . 


CAPS_WINDOW_BYTE_ALIGNMENT Specifies whether the client area of 
Vio windows should be byte-aligned. The possible values are as follows: 
Value Meaning 


CAPS_BYTE_ALIGN_REQUIRED Must be byte-aligned. 

‘CAPS_BYTE_ALIGN_RECOMMENDED More efficient if byte-aligned, but 
not required. 

CAPS_BYTE_ALIGN_NOT_REQUIRED Does not matter whether byte- 
aligned. 


CAPS_BITMAP_FORMATS. Specifies the number of bitmap formats sup- 
ported by the device. 
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CAPS_RASTER_CAPS Specifies the raster-operations capability of the 
device. The possible values are as follows: 


Value Meaning 
CAPS_RASTER_BITBLT BitBlt supported 
CAPS_RASTER_BANDING Banding supported 
CAPS_RASTER_BITBLT_SCALING Scaling supported 
CAPS_RASTER_SET_PEL Set PEL support 


CAPS._.MARKER_WIDTH Specifies the default width (in pels) of the marker 
box. 


CAPS_MARKER_HEIGHT Specifies the default depth (in pels) of the marker 
box. 


CAPS_DEVICE_FONTS Specifies the number of device-specific fonts. 


CAPS_GRAPHICS_SUBSET Specifies the graphics-drawing subset supported 
(3 indicates GOCA DR/3). 


CAPS_GRAPHICS_VERSION Specifies the graphics-architecture version sup- 
ported (1 indicates version 1). 

CAPS_GRAPHICS_VECTOR_SUBSET Specifies the graphics-vector-drawing 
subset supported (2 indicates GOCA VS/2). 
CAPS_GRAPHICS_CHAR_WIDTH Specifies the default Gpi character-box 
width (in pels). 

CAPS_GRAPHICS_CHAR_HEIGHT Specifies the default Gpi character-box 
height (in pels). 


CAPS_DEVICE_WINDOWING Specifies the support for device windows. 
This value may be CAPS_DEV_WINDOWING_SUPPORT if the device sup- 
ports windowing. 


CAPS_ADDITIONAL_GRAPHICS Specifies additional graphics support. 
The possible values are as follows: 


Value Meaning 
CAPS_GRAPHICS_KERNING_SUPPORT The device supports kerning. 
CAPS_FONT_OUTLINE_DEFAULT Outline font is the default. 
CAPS_FONT_IMAGE_DEFAULT Font image is the default. 


CAPS_SCALED_DEFAULT_MARKERS _ Scaled default markers. 


CAPS_RESERVED Specifies the maximum number of distinct colors available 
at one time. 


CAPS_PHYS_COLORS Specifies the maximum number of distinct colors that 
can be specified on the device. 


CAPS_COLOR_INDEX Specifies the maximum logical-color-table index sup- 
ported for the device. This value must be at least 7. For the EGA and VGA 
device drivers, the value is 63. 


CAPS_COLOR_PLANES Specifies the number of color planes. 


CAPS_COLOR_BITCOUNT Specifies the number of adjacent color bits for 
each pel (within one plane). 
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CAPS_COLOR_TABLE_SUPPORT Specifies the support for loadable color 


tables. It can be one of the following values: 


See Also 
Changes 


Value 


CAPS_COLTABL_RGB_8 


CAPS_COLTABLE_RGB_8_PLUS 


CAPS_COLTABLE_TRUE_MIX 


CAPS_COLTABL_REALIZE 
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constants: 


CAPS_COLOR_BITCOUNT 
CAPS_COLOR_PLANES 


CAPS_COLOR_TABLE_SUPPORT 


CAPS_COLTABL_REALIZE 
CAPS_COLTABL_RGB_8 


CAPS_COLTABLE_RGB_8_PLUS 
CAPS_COLTABLE_TRUE_MIX 
CAPS_GRAPHICS_CHAR_WIDTH 
CAPS_GRAPHICS_CHAR_HEIGHT 


H DosAllocHuge 


Meaning 


Set if the RGB color table can be 


loaded, with a minimum support 
of 8 bits each for red, green, and 
blue. 


Set if a color table with other 
than 8 bits for each primary color 
can be loaded. 


Set if true mixing occurs when the 
logical color table has been real- 
ized, providing that the size of the 
logical color table is not greater 
than the number of distinct colors 
supported (see CAPS_COLORS). 


Set if a loaded color table can be 
realized. 


DevQueryCaps can also retrieve information about colors by using the following 


Change 


USHORT DosAllocHuge( usNumSeg, usPartialSeg, psel, usMaxNumSegq, fsAtir) 


USHORT usNumSeg; 
USHORT usPartialSeg; 
PSEL psel; 

USHORT usMaxNumSeg; 
USHORT fsAttr; 


The DosAllocHuge function allocates a huge-memory block. This block consists 


/« number of segments requested 


/« number of bytes in last segment 
/« pointer to variable for selector allocated 


«/ 
»/ 
»/ 


/« maximum number of segments to reallocate »/ 


/« sharable/discardable flags 


»/ 


of one or more 65,536-byte memory segments and one additional segment of a 
specified size. 


3 


The DosAllocHuge function allocates the segments and copies the selector of 
the first segment to the variable pointed to by the psel parameter. Selectors for 


the remaining segments are consecutive and must be computed by using an offset 


from the first selector. 


Parameters 


Return Value 


Comments 
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The DosAllocHuge function can specify that segments can be shared by other 
processes. If the SEG_GETTABLE flag is used, other processes can gain 
access to the shared memory by calling the DosGetSeg function. If the 
SEG_GIVEABLE flag is used, the memory can be shared by other processes 
after the process allocating the memory has called the DosGiveSeg function. In 
both cases, the process allocating the memory must pass the selector to the pro- 
cess that will share the memory. 


The DosAllocHuge function is a family API function. 


usNumSeg Specifies the number of 65,536-byte segments to allocate. 


usPartialSeg Specifies the number of bytes in the last segment. This number 
can be any value in the range 0 through 65,535. If this value is zero, no addi- 
tional segment is allocated. 


psel Points to the variable that receives the aaeaok of the first segment. 


usMaxNumSeg Specifies the maximum number of segments that can be 
specified in any subsequent call to the DosReallocHuge function. If this number 
is zero, the memory cannot be reallocated to a size greater than its original size, 
but it can be reallocated to a smaller size. 


fsAttr Specifies the segment attributes. This parameter can be one or more of 
the following values: 
Value Meaning 


SEG_DISCARDABLE Creates a discardable, nonsharable segment. 
- Once the segment is unlocked, it may be dis- 
carded to satisfy another memory-allocation 


request. 
SEG_GETTABLE Creates a sharable segment that other processes 
can retrieve by using the DosGetSeg function. 
SEG_GIVEABLE Creates a sharable segment that the owning pro- 


cess can give to other processes by using the Dos- 
GiveSeg function. 


SEG_NONSHARED Creates a nonsharable, nondiscardable segment. 
This value cannot be combined with any other 
value. 

SEG_SIZEABLE Specifies that a shared segment can be reduced in 


size by DosReallocSeg. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_NOT_ENOUGH_MEMORY 


Each segment in the huge memory block has a unique selector. The selectors are 
consecutive. The psel parameter specifies the value of the first selector; the 
remaining selectors can be computed by adding an offset to the first selector one 
or more times—that is, once for the second selector, twice for the third, and so 
on. The selector offset is a multiple of 2, as specified by the shift count retrieved 
by using the DosGetHugeShift function. For example, if the shift count is 2, the 
selector offset is 4 (1 << 2). If the selector offset is 4 and the first selector is 6, 
then the second selector is 10, the third is 14, and so on. 
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Restrictions 


Example 


See Also 


Changes 


Corrections 


DosAllocSeg 


If necessary, the system will discard an unlocked discardable segment in order to 
satisfy another allocation request. The new allocation request can come from 
any process, including the process that allocated the segment being discarded. 


The DosFreeSeg function frees all segments when passed the first selector. If the 
segments were declared as sharable, they will not be discarded from memory 
until the last process using them calls DosFreeSeg. 


DosAllocHuge can be issued from ring 2, but the segments will be allocated as 
ring-3 segments. 


In real mode, the following restrictions apply to the DosAllocHuge function: 


mM The usPartialSeg parameter is rounded up to the next paragraph (16-byte) 
value. 


m The actual segment address is copied to the psel parameter. 
This example calls the DosAllocHuge function to allocate two segments with 64K 


and one segment with 200 bytes. It then converts the first selector to a huge 
pointer that can access all the memory allocated. 


CHAR huge *pchBuffer; 


SEL sel; 

DosAllocHuge (2, /* number of segments _ &/ 
200 /* size of last segment a/ 
&sel, /* address of selector * 
5, 7* maximum segments for reallocation */ 
SEG_NONSHARED) ; /* sharing flag 

pchBuffer = MAKEP(sel, 0); 7* converts selector to pointer a/ 


DosAllocSeg, DosFreeSeg, DosGetHugeShift, DosGetSeg, DosGiveSeg, 
DosLockSeg, DosReallocHuge, DosUnlockSeg 


SEG_SIZEABLE is a possible value for the fsAttr parameter. It allows a shared 
segment to be reduced in size by the DosReallocHuge function. 


This request can be issued from ring 2, but the segment will be allocated as a 
ring-3 segment. 


The example incorrectly requested three 64K segments instead of the two 
described. 


USHORT DosAllocSeg( usSize, psel, fsAttr) 


USHORT usSize; 
PSEL psel; 
USHORT fsAttr 


Change 
/« number of bytes requested s/ 
/« pointer to variable for selector allocated »/ 
/« sharable/discardable flags «/ 


The DosAllocSeg function allocates a memory segment and copies the segment 
selector to a specified variable. 


The DosAllocSeg function can specify that segments can be shared by other 
processes. If the SEG_GETTABLE flag is used, other processes can gain 
access to the shared memory by calling the DosGetSeg function. If the 
SEG_GIVEABLE flag is used, the memory can be shared by other processes — 
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after the process allocating the memory has called the DosGiveSeg function. 
In both cases, the process allocating the memory must pass the selector to the 
process that will share the memory. 


The DosAllocSeg function is a family API function. 
Parameters usSize Specifies the number of bytes to allocate. This number can be any 


value in the range 0 through 65,535. If this value is zero, the function allocates 
65,536 bytes. 


psel_ Points to the variable that receives the segment selector. 


fsAttr Specifies the segment attributes. This parameter can be one or more of 
the following values: 


Value Meaning 


SEG_DISCARDABLE Creates a discardable, nonsharable segment. 
Once the segment is unlocked, it may be dis- 
carded to satisfy another memory-allocation 


request. 
SEG_GETTABLE Creates a sharable segment that other processes 
can retrieve by using the DosGetSeg function. 
SEG_GIVEABLE Creates a sharable segment that the owning pro- 


cess can give to other processes by using the Dos- 
GiveSeg function. 


SEG_NONSHARED Creates a nonsharable, nondiscardable segment. 
This value cannot be combined with any other 
value. 
SEG_SIZEABLE Specifies that a shared segment can be reduced in 
size by DosReallocSeg. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be the following: 
ERROR_NOT_ENOUGH_MEMORY 


Comments If the SEG_DISCARDABLE attribute is set, the DosAllocSeg function 
automatically locks the segment. The segment cannot be discarded until the 
DosUnLockSeg function is called. Before a process accesses an unlocked dis- 
cardable segment, it must call the DosLockSeg function to determine whether 
the segment has been discarded, and to prevent the segment from being dis- 
carded while it is accessing it. 


If necessary, the system will discard an unlocked discardable segment in order to 
satisfy another allocation request. The new allocation request can come from 
any process, including the process that allocated the segment being discarded. 


The DosFreeSeg function frees the segment. If the segment was declared as 
sharable, it will not be discarded from memory until the last process using it 
calls DosFreeSeg. 


The DosAllocSeg function can allocate only up to 64K of contiguous memory. 
To allocate more than 64K, use the DosAllocHuge function. 


DosAllocSeg can be issued from ring 2, but the segment will be allocated as a 
ring-3 segment. 
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Restrictions In real mode, the following restrictions apply to the DosAllocSeg function: 


™ The usSize parameter is rounded up to the next paragraph (16-byte) 
value. 
™ The actual segment address is copied to the psel parameter. 
‘Example This example calls the DosAllocSeg function to allocate 26,953 bytes. It then 
converts the selector to a far pointer that can access the allocated bytes. 
PCH pchBuf fer; 


SEL sel; 
DosAllocSeg (26953, /* bytes to allocate we 
&sel, /* address of selector 
SEG_NONSHARED) ; /* sharing flag * 
pehBuffer = MAKEP(sel, 0); /* converts selector to pointer a/ 
See Also DosAllocHuge, DosAllocShrSeg, DosFreeSeg, DosGetSeg, DosGiveSeg, 


DosLockSeg, DosReallocSeg, DosUnlockSeg 


Changes SEG_SIZEABLE is a possible value for the fsAttr parameter. It allows a shared 
segment to be reduced in size by the DosReallocHuge function. 


This request can be issued from ring 2, but the segment will be allocated as a 
ring-3 segment. 


DosAllocShrSeg Change 
USHORT DosAllocShrSeg( usSize, pszSegName, pse!) 
‘USHORT usSize; /» number of bytes requested s/f 
PSZ pszSegName; /« pointer to segment name - af 
PSEL psel; /» pointer to variable for selector allocated »/ 


The DosAllocShrSeg function allocates a shared-memory segment and copies the 
segment selector to the specified variable. 


A shared-memory segment can be accessed by any process that can identify the 
segment name. A process can retrieve a selector for the segment by specifying 
the name in a call to the DosGetShrSeg function. (Shared segments allocated by 
using the DosAllocSeg function must be explicitly given or retrieved by using the 
DosGiveSeg and DosGetSeg functions.) 


Parameters. usSize Specifies the number of bytes to be allocated. This number can be any 
value in the range 0 through 65,535. If this value is zero, the function allocates 
65,536 bytes. 


pszSegName _ Points to a null-terminated string that identifies the shared 
memory segment. The string must have the following form: 


\sharemem\Wiame 


The segment name (name) must have the same format as. an MS OS/2 filename 


and must be unique. For example, the name \sharemem\public.dat is accept- 
able. 


psel Points to the variable that receives the segment selector. 


Return Value 


Comments 


Example 


See Also 


Changes 


DosCopy 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ALREADY_EXISTS 
ERROR_INVALID_NAME 
ERROR_NOT_ENOUGH_MEMORY 


A process can allocate up to 256 shared segments. The number of segments that 
can be allocated may be less due to system usage at the time the allocation 
request is made. 


The DosFreeSeg function frees the segment. The segment will not be discarded 
from memory until the last process using it calls DosFreeSeg. 


DosAllocShrSeg can be issued from ring 2, but the shared-memory segment will 
be allocated as a ring-3 segment. 


This example calls the DosAlocShrSeg function to allocate 26,953 bytes. It gives 
the memory the name “\sharemem\abc.mem” so that other processes can use 
the memory if they know the name. 


SEL sel; 

DosAllocShrSeg (26953, /* bytes to allocate a/ 
"\\sharemem\\abc.mem", /* memory name * 
&sel); /* selector address */ 


DosAllocHuge, DosAllocSeg, DosFreeSeg, DosGetSeg, DosGetShrSeg, 
DosGiveSeg 


The number of segments a process can allocate has been increased to approxi- 
mately 256 (the actual number varies according to system usage). 


The error message ERROR_LINVALID_HANDLE has been changed to 
ERROR_INVALID_NAME. 


New 


USHORT DosCopy( pszSrc, pszDest, usOpt, ulReserved) 


PSZ pszSre; 

PSZ pszDest; 
USHORT usOpt; 
ULONG u/Reserved; 


Parameters 


/» pointer to name of source file «/ 
/» pointer to name of target file / 
/« options «/ 
/« must be zero «/ 


The DosCopy function copies a file or subdirectory. 


pszSrc Points to the null-terminated string that specifies the file or directory to 
copy. This string must be a valid MS OS/2 filename and cannot contain wildcard 
characters. 


pszDest Points to the null-terminated string that specifies the name of the file, 
directory, or device to copy the value of pszSrc to. This string must be a valid 
MS OS/2 filename and cannot contain wildcard characters. 
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Return Value 


Comments 


Example 


See Also 


usOpt Specifies an option that can be used in the copy operation (it is ignored 
if the destination is a device). This parameter can be one of the following values: 


Value Meaning 


DCPY_EXISTING Copy the source file to the destination file, even if 
the destination file already exists. If neither this 
option nor the DCPY_APPEND option is 
specified, and the file exists, the value 
ERROR_ACCESS_DENIED is returned. 


DCPY_APPEND Append the data in the source file to the end of 
the destination file. If the destination file does not 
exist, a new file is created. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DIRECTORY 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INSUFFICIENT_DISK_SPACE 
ERROR_INVALID_PARAMETER 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 


The DosCopy function can be used to copy individual files or entire directories 
(including any subdirectories within the directory). The source and destination 
files can be on different drives. 


If an I/O error occurs when a file is being copied, the destination file is deleted 
from the destination directory unless the DCPY_APPEND option is specified. In 
this case, the destination file is restored to its original size. 


The DosCopy function copies the attributes of the source to the destination file, 
except when appending to an existing file. 


You cannot specify only the drive as the destination. You must give the path on 
the drive where the file or directory is to be copied. 


This example copies the directory xyz from drive C, including its files and sub- 
directories, to the root directory on drive A. 


DosCopy ("c:\\xyz", /* source directory a/ 
"as\\", * destination directory a/ 
DCPY_EXISTING, | /* replaces existing files */ 
OL); /* reserved */ 


DosMove 


M DosCreateSem 
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Correction 


USHORT DosCreateSem( fExclusive, phssm, pszSemName) 


USHORT fExclusive; 
PHSYSSEM phssm; 
PSZ pszSemName; 


Parameters 


Return Value 


Comments 


Example 


See Also 


Corrections 


/« exclusive/nonexclusive ownership flag »/ 
/» pointer to variable for semaphore handle »/ 
/« pointer to semaphore name »/ 


The DosCreateSem function creates a system semaphore and copies the sema- 
phore handle to a variable. A process can use a system semaphore to indicate to 
another process a change in the status of a shared resource. 


fExclusive Specifies ownership of the semaphore. If this parameter is 
CSEM_PRIVATE, the process receives exclusive ownership. If this parameter 
is CSEM_PUBLIC, the process does not receive exclusive ownership. 


phssm Points to the variable that receives the semaphore handle. 


pszSemName Points to a null-terminated string that identifies the semaphore. 
The string must have the form \sem\zame. The string name, name, must have 
the same format as an MS OS/2 filename and must be unique. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ALREADY_EXISTS 
ERROR_INVALID_NAME 
ERROR_INVALID_PARAMETER 
ERROR_TOO_MANY_SEMAPHORES 


The process calling DosSemCreate receives exclusive ownership of the sema- 
phore if the CSEM_PRIVATE flag is set in the fExclusive parameter. Exclusive 
ownership prevents other processes from setting or clearing the semaphore. 
Other processes can open the semaphore and wait for it to change status, but 
they cannot change its status. Another process can obtain ownership of the 
semaphore, however, by calling the DosSemRequest function. If ownership of 
the semaphore changed through DosSemRequest, the process that originally 
called DosCreateSem no longer has ownership. It cannot change the status of 


the semaphore until it regains ownership by calling DosSemRequest. 


This example calls DosCreateSem to create a system semaphore, and then calls 
DosSemSet to set it and DosSemClear to clear it: 


HSYSSEM hssm; /* handle to semaphore */ 
DosCreateSem(CSEM_PRIVATE, ‘ /* specifies ownership */ 
&hssm, /* address of handle a/ 
"\\sem\\abc.sem") ; /* name of semaphore a/ 
DosSemSet (hssm) ; /* sets semaphore * 
DosSemClear (hssm) ; /* clears semaphore */ 


DosCloseSem, DosMuxSemWait, DosOpenSem, DosSemClear, 
DosSemRequest, DosSemSet, DosSemSetWait, DosSemWait 


The comments incorrectly indicated that the semaphore is always owned by the 
process that calls DosCreateSem. The semaphore is owned by the calling pro- 
cess only if the CSEM_PRIVATE flag is set in the fExclusive parameter. 
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™ DosCreateThread Correction 
USHORT DosCreateThread( pfnFunction, ptidThread, pbThrdStack) 
PFNTHREAD pfnFunction(VOID); /« pointer to function »/ 
PTID ptidThread; /« pointer to variable for thread identifier »/ 
PBYTE pbThrdStack; /» pointer to thread stack »/ 


The DosCreateThread function creates a new thread. 


Parameters pfnFunction Points to the application-supplied function and represents the 
starting address of the thread. For a full description, see the following “Com- 
ments” section. 


ptidThread Points to the variable that receives the thread identifier. 
pbThrdStack Points to the stack of the new thread. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NO_PROC_SLOTS 
ERROR_NOT_ENOUGH_MEMORY 


Comments When a thread is created, the system makes a far call to the application-supplied 
function whose address is specified by the pfnFunction parameter. This function 
can include local variables and can call other functions, as long as the thread’s 
stack has sufficient space. (The stack can be allocated by using the DosAllocSeg 
function or by using a global array.) The address specified by the pb ThrdStack 
parameter should be the address of the last word in the stack, not the first, 
because the stack grows down in memory. The thread terminates when the func- 
tion returns or calls the DosExit function. 


The pfnFunction parameter points to a function supplied by the program. This 
function should have the following form: 


VOID FAR FuncName (VOID) 
} 


Because the system passes no arguments, no parameters are defined. 


A new thread inherits all files and resources owned by the parent process. Any 
thread in a process can open a file, device, pipe, queue, or system semaphore. 
Other threads can use the corresponding handles to access the given item. 


Note that high-level languages, run-time libraries, and stack checking may 
severely limit or eliminate the ability to call the DosCreateThread function 
directly from a high-level-language program. For more information, consult the 
documentation that came with your language product. 


Before calling the DosCreateThread function, set the es register to zero or 
assign to it a selector that will remain valid for the duration of the new thread. If 
you fail to set the es register to one of these values, the thread may unexpectedly 
terminate as a result of a general protection fault. 


Example This example sets aside a 2K buffer to be used as stack space for any threads 
\ created. The first stack is set at the end of the array. The thread is created by 
calling the DosCreateThread function. The thread terminates by calling the 
DosExit function. 


See Also 


Corrections 


DosDeviOCtl2 
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VOID FAR Threadl(); 
BYTE abStackArea [2048]; 


PVOID pStackl = abStackArea + sizeof (abStackArea) ; 
TID tidThreadl; 


DosCreateThread (Thread1, /* name of thread function */ 
&tidThread1, /* address of thread ID */ 
pStackl) ; /* thread's stack a/ 


DosExit (EXIT_PROCESS, 0); 
VOID FAR Threadi1() { 
DosExit (EXIT_THREAD, 0); 


DosAllocSeg, DosExit, DosResumeThread, DosSuspendThread 


The example indicated that a 512K-byte stack was allocated. This has been 
changed to a 2K-byte stack. 


New 


USHORT DosDevlOCtl2( pvData, cbData, pvParmList, cbParmList, usFunct, usCat, hDev) 


PVOID pvData; 
USHORT cbData; 
PVOID pvParmList; 


/» pointer to buffer for data »/ 
/ length of data buffer »/ 
/« pointer to list of parameters +/ 


USHORT cbParmList; /«fength of parameter list «/ 


USHORT usFunct; 
USHORT usCat; 
HFILE hDev; 


Parameters 


/» function code »/ 
/» device category x/ 
/» device handle »/ 


The DosDevIOCtl2 function performs control functions on the device specified 
by the file or device handle. 


pvData Points to a data buffer. 
cbData Specifies the length (in bytes) of the data buffer. 
pvParmList Points to an argument list for a specified command. 


cbParmList Specifies the length (in bytes) of the argument list for a specified 
command. 


usFunct Specifies a function code for a specified device. This parameter can 
be any value from 0 through 255. 


usCat Specifies a device category. This parameter can be any value from 0 
through 255. 


hDev Identifies the device. This handle must have been created previously by 
using the DosOpen function. 
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Return Value 


Comments 


See Also 


DosEditName 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_CATEGORY 
ERROR_INVALID_DRIVE 
ERROR_INVALID_FUNCTION 
ERROR_LINVALID_HANDLE 
ERROR_INVALID_PARAMETER 


This function provides a way for a program to implement a customized IOCtl 
function. 


If the pyData parameter is zero, this parameter is not defined for the IOCtl func- 
tion being specified, and the value passed in the cbData parameter is ignored. 


If the pyParmList parameter is zero, this parameter is not defined for the IOCtl 
function being specified, and the value passed in the cbParmList parameter is 
ignored. 


Whenever the pvData or pvParmList parameter is a value other than zero, the 
associated length parameter cannot be zero. The length parameters are not 
passed to device drivers that do not support them. 


DosDevIOCtl 


New 


USHORT DosEditName( usEditLevel, pszSrc, pszEdit, pszDst, cbDst) 
USHORT usEditLevel; /» edit level »/ 


PSZ pszSre;. 
PSZ pszEdit; 
PBYTE pszDst; 
USHORT cbDst; 


Parameters 


Return Value 


/« pointer to source string «/ 
/» pointer to editing string «/ 
/« pointer to target buffer -»/ 
/« length of target buffer —«/ 


The DosEditName function copies a source string to a revised destination string 
by using an editing string and rules for converting wildcard characters. 


usEditLevel Specifies the version of editing semantics to use in changing the 

copy of the source string. (Editing semantics are the rules used by the system to 
convert wildcard characters.) For MS OS/2, version 1.2, this parameter must be 
0x0001. 


pszSrc__ Points to the null-terminated string to copy. The string should contain 
only the component of the path to be edited, not the entire path. 


pszEdit Points to the null-terminated string to use for editing. 

pszDst Points to the buffer that contains the new string. 

cbDst Specifies the length (in bytes) of the buffer pointed to by the pszDst 
parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_LINVALID_NAME 
ERROR_INVALID_PARAMETER 
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Comments For MS OS/2, version 1.2, the destination string is always converted to upper- 
case. 
The DosEditName function is typically used in copy and rename/move opera- 
tions. , 
Example This example takes the source name abc.txt and an editing string of *.doc and 
calls DosEditName to produce the string ABC.DOC: 
CHAR szDst [14]; 
DosEditName(1, "abc.txt", "*.doc", szDst, sizeof (szDst)); 
DosEnterCritSec Change 


USHORT DosEnterCritSec( VOID) 


Return Value 


-Comments 


See Also 


Changes 


The DosEnterCritSec function suspends execution of all threads in the current 
process, except for the calling thread. Suspended threads cannot execute until 
the current thread calls the DosExitCritSec function. 


This function has no parameters. 


The return value is zero if the function is successful. Otherwise, it is an error | 
value, which may be the following: 


ERROR_CRITSEC_OVERFLOW 


The signal handler (if installed) is not suspended when the DosEnterCritSec 
function is called. If a signal occurs, the processing done by the signal handler 
must not interfere with the processing done by the thread calling the DosEnter- 
CritSec function. 


MS OS/2 maintains the number of outstanding DosEnterCritSec requests. This 
count is incremented by DosEnterCritSec requests and decremented by Dos- 
ExitCritSec requests. If the count is greater than zero, a DosExitCritSec request 
will not restore normal thread execution. If the count exceeds 65535, the error 
ERROR_CRITSEC_OVERFLOW will be returned. 


DosCreateThread, DosExitCritSec, DosHoldSignal, DosSetSigHandler 
DosEnterCritSec now returns zero if the function is successful. Otherwise, it 
returns an error value. It did not return a value in earlier versions. 


For MS OS/2, version 1.2, a count is maintained of the number of times Dos- 
EnterCritSec is called. Normal thread execution is not restored until an equal 
number of calls are made to DosExitCritSec. 
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DosEnumAttribute . New 
USHORT DosEnuméttribute ( usRefType, pvFile, ulEntry, pvBuf, cbBuf, pulCount, ullnfoLevel, ulReserved) 
USHORT usRefType; /« reference type »/ 

PVOID pvFile; /« filename/handle »/ 

ULONG u/Entn; /» starting entry in list »/ 

PVOID pvBuf; /« data buffer »/ 

ULONG cbBuf; /» buffer size »/ 

PULONG pu/Count; /« number of entries to return »/ 

ULONG ullnfoLevel; /« info level »/ 

ULONG u/Reserved; /» reserved »/ 


The DosEnumAttribute function enumerates extended attributes for a specified 
file or subdirectory. 


The DosEnumAttribute function is a family API function. 


Parameters usRefType Specifies whether the pvFile parameter points to a file handle or to 
a string that contains a file or directory name. This parameter can be one of the 
following values: 


Value : Meaning 


ENUMEA_REFTYPE_FHANDLE A handle 
ENUMEA_REFTYPE_PATH File or directory name 


pvFile Points to the handle obtained from the DosOpen or DosOpen2 func- 
tion or to a null-terminated string that contains a file or directory name. 


ulEntry Specifies where to start enumerating extended attributes. A value of 1 
specifies the first attribute for the file. 


pvBuf Points to the buffer that receives the extended attributes. For a 
ENUMEA_LEVEL_NO_VALUE-level request, the buffer is in the form of a 
DENAI structure that contains only the names of the extended attributes. The 
DENAI structure has the following form: 
typedef struct _DENA1 { 

UCHAR reserved; 

UCHAR cbName; 

USHORT cbValue; 


UCHAR szName[1]; 
} DENAI; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbBuf Specifies the length (in bytes) of the buffer pointed to by the pvBuf 
parameter. 


pulCount Points to the variable that specifies the number of extended attri- 
butes requested and, on return, contains the number retrieved. A value of 
OxFFFFFFFF returns as many extended attributes as will fit in the supplied 
buffer. 


ulInfoLevel Specifies the information level requested. For MS OS/2, version 
1.2, the only possible value is ENUMEA_LEVEL_NO_VALUE. 


ulReserved Specifies a reserved value; must be zero. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_HANDLE 
ERROR_ACCESS_DENIED 
ERROR_PATH_NOT_FOUND 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_LEVEL 
ERROR_INVALID_PARAMETER 
ERROR_BUFFER_OVERFLOW 


Comments The order in which attributes are returned may not be the same if the Dos- 
EnumAttribute function is called a second time because other threads or 
processes may have changed the order. 


Example This example allocates 1K of memory for the extended-attribute names, calls 
DosEnumAttribute to retrieve the extended-attribute names for the file eafile, 
and then displays the names one at a time: 


#define BUFSIZE 


SEL sel; 

PDENA1 pdenal; 
ULONG ulCount; 
USHORT offset = O; 


DosAllocSeg (BUFSIZE, &sel, SEG_NONSHARED); /* allocates buffer s/ 
pdenal = MAKEP(sel, 0); /* initializes pointer to buffer */ 
ulCount = OxFFFEFFFFEF; 
if (!DosEnumAttr ibute (ENUMEA_ REFTYPE_PATH, /* path supplied */ 
“eafile", /* filename a/ 
1L, /7/* starts enum. with first attr. s/ 
pdenal, 7* buffer address */ 
BUFSIZE, /* buffer size a/ 
&ulCount, /7* number of attributes to retrieve */ 
ENUMEA_LEVEL_NO_VALUE, /* type of request s 
OL /* reserved a/ 
while (ulCount--) * while there are attribute names */ 


{ / 
VioWrtTTY (pdenal- >szName, (USHORT) pdenal->cbName, OL); 
VioWrtTTY("\r\n", 2, OL 
offset += sizeof (DENA1) + pdenal->cbName; 
pdenal = MAKEP(sel, offset); /* points to next name */ — 


HM DosExitCritSec Change 
USHORT DosExitCritSec( VO/D) 


The DosExitCritSec function restores execution of all threads suspended by the 
DosEnterCritSec function. 


This function has no parameters. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_CRITSEC_LUNDERFLOW 


Comments 


See Also 
Changes 


DosExitList 
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MS OS/2 maintains the number of outstanding DosEnterCritSec requests. This 
count is incremented by DosEnterCritSec requests and decremented by Dos- 
ExitCritSec requests. If the count is greater than zero, a DosExitCritSec request 
will not restore normal thread execution. If the count is less than zero, the 
ERROR_CRITSEC_UNDERFLOW will be returned. 


DosCreateThread, DosEnterCritSec 


DosExitCritSec now returns an error value if it is called without a corresponding 
call to DosEnterCritSec. 


Correction 


USHORT DosExitList ( fFnCode, pfnFunction) 


USHORT fFnCode; 


/» function code «/ 


PFNEXITLIST pfnFunction(USHORT); /» pointer to address of function »/ 


Parameters 


Return Value 


The DosExitList function specifies a function that is executed when the current 
process ends. This “termination function” can define additional termination 
functions. The DosExitList function can be called one or more times: each call 
adds or subtracts a function from an internal list maintained by the system. 
When the current process terminates, MS OS/2 transfers control to each func- 
tion in the list. 


fFnCode Specifies whether a function’s address is added to or removed from 
the list. If the function is added, the high byte of this parameter specifies the 
order in which the function should be called. The exit-list routines with a low- 
order high byte will be called before those with a high-order high byte. The low 
byte of this parameter can be one of the following values: 


Value Meaning 


EXLST_ADD Adds the function to the termination list. If this flag is 
specified, the high byte of the parameter specifies the 
order in which the function is called. It can be a value 
from 0 through 255. A value of 0 specifies that this 
function is to be called first. In the event of duplicate 
order numbers, the last function added with the dupli- 
cate order number is called before the first function 
added with the duplicate order number. 


EXLST_EXIT Termination processing is complete. Calls the next 
function on the termination list. 
EXLST_REMOVE Removes the function from the termination list. 


pfnFunction Points to the termination function to be added to the list. For a 
full description, see the following “Comments” section. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_DATA 
ERROR_NOT_ENOUGH_MEMORY 


Comments 


Example 
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"When adding an exit-list function, it is important that the exit-list function not 


call any system functions with a lower exit-list order. The order is determined by 
the high-byte of the fFnCode parameter. The following list defines the orders of 
the various system components: 


Order Component 

0x80-0x88 Extended Edition Database Manager 
0x90-0x98 Extended Edition Communication Manager 
0xA0-0xA8 Presentation Manager 

0xBO KBD component 

0xCO VIO component 

0xDO IPC Queues component 


Dynamic-link-library modules often use the DosExitList function. It allows 
dynamic-link-library modules to free resources or clear flags and semaphores if 
the client process terminates without notifying them. 


The termination function has one parameter and no return value. The function 
should have the following form: 


VOID PASCAL FAR FuncName (usTermCode) 
USHORT usTermCode; 


£ 


DosExitList (EXLST_EXIT, NULL); 


The usTermCode parameter of the termination function specifies the reason the 
process ended. This parameter can be one of the following values: 


Value Meaning 

TC_EXIT Normal exit 
TC_HARDERROR Hard-error abort 
TC_KILLPROCESS Unintercepted DosKillProcess 
TC_TRAP Trap operation 


Before transferring control to the termination function, MS OS/2 resets the 
stack to its initial value. MS OS/2 then passes control to the function by using a 
jmp instruction. The termination function should carry out its tasks and then 
call the DosExitList function with the fFnCode parameter set to EXLST_EXIT. 
This parameter setting directs the system to call the next function on the termi- 
nation list. When all functions on the list have been called, the process ends. 


Termination functions should be as short and fail-safe as possible. Before the 
termination functions are executed, all threads except for the one executing the 
DosExitList function are destroyed. Note that a termination function must call 
the DosExitList function to end; otherwise, the process “hangs” because MS 
OS/2 cannot terminate it. 


A termination function can call most MS OS/2 system functions; however, it 
must not call the DosCreateThread or DosExecPgm function. 


This example calls DosExitList, which then adds the locally defined function 
CleanUp to the list of routines to be called when the process terminates. 
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See Also 


Corrections 


DosFilelO 


The CleanUp function displays a message that it is cleaning up, and then calls 
DosExitList, reporting that it has finished and that the next function on the ter- 
mination list can be called. 


/* Add the function, and have it be called last. */ 


DosExitList(EXLST_ADD | OxFFOO, CleanUp); 


DosExit (EXIT_PROCESS, 0); 
VOID PASCAL FAR CleanUp (usTermCode) : 
USHORT usTermCode; 


VioWrtTTY ("Cleaning up...\r\n", 16, 0); 


DosExitList (EXLST_EXIT, /* termination complete */ 
NULL) ; 
+ 


DosCreateThread, DosExecPgm, DosExit, DosKillProcess 


When the EXLST_ADD constant is used in the fFnCode parameter, the high 
byte of the parameter contains an order number (0 through 255). You can use 
this number to specify the order in which your exit-list function is called. 


The function template in the example incorrectly listed the prototype of the ter- 
mination function as PFNEXITLIST. It should be VOID PASCAL FAR. 


USHORT DosFilelO( hf, pbCmd, cbCmd, pusErr) 


HFILE hf; 

PBYTE pbCmd; 
USHORT cbCma; 
PUSHORT pusErr; 


Parameters 


New 
/« file handle s/ 
/« pointer to buffer for commands «/ 
/« length of command buffer »/ 
/« pointer to error offset s/ 


The DosFileIO function performs multiple lock, unlock, seek, read, and write 
operations on a file. 


hf Identifies the file on which to perform the commands. This handle must 
have been created previously by using the DosOpen function. 


pbCmd Points to the buffer that contains one or more of the following 
structures: FIOLOCKCMD, FIOLOCKREC, FIOUNLOCKCMD, 
FIOUNLOCKREC, FIOSEEKCMD, or FIOREADWRITE. The structures have 
the following forms: 


typedef struct _FIOLOCKCMD { 
USHORT usCmd; 
USHORT cLockCnt; 
ULONG cTimeOut; 

} FIOLOCKCMD; 


typedef struct  FIOLOCKREC { 
USHORT fShare; 
ULONG cbStart; 
ULONG cbhLength; 

} FIOLOCKREC; 


Return Value 


Comments 
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typedef struct  FIOUNLOCKCMD {. 
USHORT usCmd; 
USHORT cUnlockCnt; 

} FIOUNLOCKCMD; 


typedef struct VJFIOUNLOCKREC { 
ULONG cbStart; 
ULONG cbLength; 

} FIOUNLOCKREC; 


typedef struct -_FIOSEEKCMD { 
USHORT usCmd; 
USHORT fsMethod; 
ULONG cbDistance; 
ULONG cbNewPosition; 
} FIOSEEKCMD; 


typedef struct W_FIOREADWRITE { 
USHORT usCmd; 
PVOID pbBuffer; 
USHORT cbBufferLen; 
USHORT cbActualLen; 
} FIOREADWRITE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
cbCmd _ Specifies the length (in bytes) of the pbCmd parameter. 


pusErr Points to a variable that receives the byte offset of the structure that 
caused an error. The offset is relative to the beginning of the buffer pointed to 
by the pbCimd parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED - 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_INTERRUPT 
ERROR_LINVALID_HANDLE 
ERROR_INVALID_PARAMETER 
ERROR_LOCK_VIOLATION 
ERROR_NEGATIVE_SEEK 
ERROR_SEEK_ON_DEVICE 
ERROR_SHARING_BUFFER_EXCEEDED 


The DosFileIO function allows you to combine the following operations into a 
single function call: 


@ Locking and unlocking multiple file ranges 
m@ Changing the file-position pointer 
™ Reading and/or writing 


Combining these operations into one call can improve system performance, par- 
ticularly in a networking environment. — 


The DosFileIO function provides a simple mechanism for denying other 
processes read/write or write access to regions of the file. If another process 
attempts to read from or write to a no-access region, or attempts to write in a 
read-only region, an error is returned. If a time-out occurs before the locking 
operation is complete, DosFileIO returns an error to the calling process. 


Since the calling process may return after the time-out period has expired 
without receiving an ERROR_SEM_TIMEOUT message, semaphore time-out 
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values should not be used for exact timing or for determining the sequence of 
_I/O operations. 


Before a range is locked, it must be cleared of any locked subranges or locked 
overlapping ranges. 


Each I/O operation completes before the next one begins. The operations con- 
tinue until all are complete or until one fails. 


Example This example opens the file abc.txt, allocates memory for the command buffer, 
initializes the commands in that buffer, and calls DosFileIO to move the file 
10 bytes into the file and then read from the file: 


HFILE hf; 

USHORT usAction; 
SEL sel; 

BYTE abBuf[512]; 
LONG lError; 


PFIOREADWRITE pfiorw; 
PFIOSEEKCMD pfioseek; 


DosOpen("“abc.txt", &hf, &usAction, OL, FILE_NORMAL, FILE_OPEN, 
OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, OL); 
DosAllocSeg(sizeof(FIOSEEKCMD) + sizeof (FIOREADWRITE), 
&sel, SEG_NONSHARED) ; 


pfioseek = MAKEP(sel, 0); 
pfioseek->usCmd = FIO_SEEK; 
pfioseek->fsMethod = FILE_BEGIN; 
pfioseek->cbDistance = 10L; 


pfiorw = MAKEP(sel, sizeof (FIOSEEKCMD) ) ; 
pfiorw->usCmd = FIO_READ; 
pfiorw->pbBuffer = (PVOID) abBuf; 
pfiorw->cbBufferLen = sizeof (abBuf) ; 


DosFilelIO(hf, /* file handle */ 

MAKEP({sel, 0), /* buffer address */ 
(sizeof (FIOSEEKCMD) + sizeof (FIOREADWRITE) ) , /* buffer size */ 
&lError); /* address of error variable a/ 

See Also DosChgFilePtr, DosFileLocks, DosOpen, DosRead, DosWrite 

DosFindFirst2 New 

USHORT DosFindFirst2( pszFileName, phDir, usAttribute, pBuf, cbBuf, pusSearchCount, usinfoLevel, 

ulReserved) 

PSZ pszFileName; /« pointer to filename »/ 

PHDIR phDir /« pointer to directory handle »/ 

USHORT usAttribute; /« attributes of file to be found —«/ 

PVOID pBuf; /» pointer to buffer for results —»/ 

USHORT cbBuf; /« size of results buffer »/ 

PUSHORT pusSearchCount; /« number of entries found s/ 

USHORT usinfoLevel; /« level of information to retrieve «/ 

ULONG u/Reserved; /« must be zero a/ 


The DosFindFirst2 function searches a directory for the file or files whose 
filename and attributes match the specified filename and attributes. 


The DosFindFirst2 function is a family API function. 
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Parameters pszFileName Points to a null-terminated string. This string must be a valid 
MS OS/2 path and can contain wildcard characters. 


phDir Points to the variable that contains the handle of the directory to 
search. 


usAttribute Specifies the file attribute(s) of the file to be located. This param- 
eter can be a combination of the following values: 


Value Meaning 
FILELNORMAL Search for normal files. 
FILELREADONLY Search for read-only files. 
FILE_HIDDEN Search for hidden files. 
FILE_SYSTEM Search for system files. 
FILE_DIRECTORY Search for subdirectories: 
FILE_ARCHIVED Search for archived files. 


pBuf Points to the buffer in which the file information is returned. The format 
for this buffer is determined by the value specified in the usInfoLevel parameter. 


cbBuf Specifies the size (in bytes) of the buffer pointed to by pBuf. 


pusSearchCount Points to the variable that specifies the number of matching 
entries to locate. The DosFindFirst2 function copies the number of entries 
found to this parameter before returning. 


usInfoLevel Specifies the type of file information to retrieve. This parameter 
can be one of the following values: 


Value Meaning 


FIL_STANDARD Return a FILEFINDBUF structure with the 
results of the search. The information 
returned is identical to that returned by the 
DosFindFirst function. 


FIL_QUER YEASIZE Return a FILEFINDBUFZ2 structure with the 
results of the search, and that contains the 
size of the buffer needed to retrieve the 
extended attributes. 


FIL_QUERYEASFROMLIST Return a buffer that contains both the file 
information and the extended attributes for 
the file. 


The FILEFINDBUF structure has the following form: 


typedef struct _FILEFINDBUF { 
FDATE fdateCreation; 
EFTIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
FDATE fdateLastWrite; 
ETIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 
UCHAR cchName; 
CHAR achName [13]; 

} FILEFINDBUE; 
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Return Value 


Comments 


The FILEFINDBUIF2 structure has the following form: 


typedef struct  FILEFINDBUF2 { 
FDATE fdateCreation; 
ETIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
FDATE  fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG chFileAlloc; 
USHORT attrFile; 
USHORT cbList; 
UCHAR cchName; 
CHAR achName [13]; 

} FILEFINDBUF2; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_EAS_DIDNT_FIT 
ERROR_EA_LIST_INCONSISTENT 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_EA_NAME 
ERROR_LINVALID_HANDLE 
ERROR_INVALID_PARAMETER 
ERROR_META_EXPANSION_TOO_LONG 
ERROR_NO_MORE_FILES 
ERROR_NO_MORE_SEARCH_HANDLES 
ERROR_PATH_NOT_FOUND 


. The DosFindNext function uses the directory handle pointed to by the phDir 


parameter of the DosFindFirst2 function to repeat the search. If DosFindFirst2 
returns an error value other than ERROR_EAS_DIDNT_FIT, no directory han- 
dle is allocated. 


If the phDir parameter is HDIR_SYSTEM, the system-default search-directory 
handle is used; any previous search that used HDIR_SYSTEM terminates if this 
parameter is HDIR_CREATE, the search directory used by the process is 
created, and the function copies the handle of this search directory to the vari- 
able pointed to by the phDir parameter. If the handle was created by a previous 
call to DosFindFirst, it can be used in subsequent calls to DosFindNext. 


If the value of the usInfoLevel parameter is FILELQUERYEASIZE, the cbList 
field of the FILEFINDBUF2 structure can be used to calculate the size of the | 

buffer necessary for a FILELQUERYEASFROMLIST information request. For 
MS OS/2 version 1.2, the value of cbList will never exceed 65,535. 


To use a FILELQUERYEASFROMLIST information request, you must supply 
a buffer large enough for an EAOP structure and a FILEFINDBUF structure, 
plus enough space for the the extended attributes. You must initialize the first 
portion of this buffer as an EAOP structure, and fill in the GEALIST structure 
with the extended-attribute names to retrieve..On return, the EAOP structure 
will be unchanged. It will be followed immediately by a FILEFINDBUEF2 struc- . 
ture, without the last three fields. This is followed by an FEALIST structure (the 
address is the same as the cbList field of the FILEFINDBUEF2 structure). The 
FEALIST structure is in turn followed by a single byte that specifies the length of 
the filename, and that is followed by a null-terminated string that specifies the 
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filename. For an example of how to use structure pointers to access each of 
these fields, see the “Example” section. 
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If there is not enough room in the output buffer to hold the extended-attribute 
information, the error ERROR_EAS_DIDNT_FIT is returned. The search han- 
dle will be allocated, however, and can be used in subsequent calls to the Dos- 
FindNext function. If no extended attribute is found, the FEA structure for that 
extended attribute will contain the name of the attribute, but the cbValue field 


will be zero. 


Example This example shows how to set up pointers to access the various fields of the 

buffer returned by a FILLQUERYEASFROMLIST level request: 
/7/* Declare a structure to retrieve the .TYPE attribute name. */ 
typedef struct _TYPEATTR { 

ULONG cbList; 

BYTE cbName; 

CHAR szName[6]; 
} TYPEATTR; 
#define BUFSIZE 2 * 1024 /* default buffer size */ 
SEL sel; /* selector for buffer a/ 
HDIR hdir = HDIR_CREATE; /* directory handle a/ 
USHORT usSearchCount = 1; 7* number of files to retrieve */ 
TYPEATTR typeattr; /* TYPE attribute structure */ 
PEAOP peaop; 
PFILEFINDBUF2 pfindbuf2; 
PFEALIST pfeal; 
PSZ pszFileName; 
PUCHAR pechFileName; 
DosAllocSeg(BUFSIZE, &sel, SEG_NONSHARED); /* creates buffer a/ 
peaop = MAKEP(sel, 0); /* sets up peaop pointer */ 
typeattr.cbList = sizeof (TYPEATTR) ; /7* structure size a/ 
strepy (typeattr.szName, ",.TYPE"); * EA name */ 
typeattr.cbName = sizeof (typeattr.szName) - 1; /* name length */ 
peaop->fpGEAList = (PGEALIST) &typeattr; /* size of GEALIST struc. */ 
if (!DosFindFirst2("eafile", &hdir, FILE_NORMAL, 

peaop, BUFSIZE, 
&usSearchCount, FIL_QUERYEASFROMLIST, OL)) { 

pfindbuf2 = MAKEP(sel, sizeof (EAOP)); /* EFILEFINDBUF structure */ 

pfeal = (PFEALIST) &pfindbuf2->cbList; /* FEALIST structure a/ 

pechFileName = ((PSZ) pfeal) + pfeal->cbList; /* filename length */ 

pszFileName = pechFileName + 1; /* filename */ 
} 

See Also DosFindClose, DosFindFirst, DosFindNext, DosQFileMode, DosQFSInfo 
. DosFindNext Chan 


USHORT DosFindNext( hdir, pfindbuf, cbfindbuf, pcSearch) 


HDIR hdir; 


/« handle of search directory «/ 


PFILEFINDBUF pfindbuf; /« pointer to structure for search result «/ 


USHORT cbfindbuf; 


/« length of result buffer »/ 


PUSHORT pcSearch; /« pointer to variable for file count »/ 


ge 


The DosFindNext function searches for the next file or group of files matching 


the specified filename and attributes. The function copies the name and 


requested information about the file to the specified structure. The information 


94 DosFindNext 


Parameters 


Return Value 


Comments 


Restrictions 


Example 


returned is as accurate as the most recent call to the DosClose or DosBufReset 
function. 


The DosFindNext function is a family API function. 


hdir Identifies the search directory and the filename(s) to search for. This 
handle must have been created previously by using the DosFindFirst function. 


pfindbuf Points to the structure that receives the result of the search. This 
structure will be either a FILEFINDBUF or FILEFINDBUF2 structure, depend- 
ing on the information level requested in the DosFindFirst or DosFindFirst2 
function that preceded this function. For specific information on the format of 
these structures, see the DosFindFirst and DosFindFirst2 functions. 


cbfindbuf Specifies the length (in bytes) of the structure pointed to by the 
pfindbuf parameter. 


pcSearch Points to the variable that specifies the number of matching 
filenames to locate. The function copies the number of filenames found to the 
variable before returning. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_HANDLE 
ERROR_LINVALID_PARAMETER 
ERROR_NO_MORE_FILES 
ERROR_NOT_DOS_DISK 
ERROR_EAS_DIDNT_FIT 


The pcSearch parameter specifies the number of files to search for. The number 
of files whose information is copied is the number of files requested, the number 
of files whose information fits in the structure, or the number of files that exist, 
whichever is smallest. If you want to obtain information for more than one file, 
the pfindbuf parameter must point to a buffer that consists of consecutive struc- 
tures. If the DosFindNext function fails to find a match or cannot copy all the 
information about the file to the structure, it returns an error. 


In real mode, the following restriction applies to the DosFindNext function: 
m= The hdir parameter must be set to HDIR_SYSTEM. 


This example calls the DosFindFirst function to find all files matching “*.*”, and 
then uses the DosFindNext function to display them one at a time: 


FILEFINDBUE findbuf; 

HDIR hdir = HDIR_CREATE; 

USHORT cSearch = 1; 

DosFindFirst("*.*", &hdir, FILE_NORMAL, &findbuf, sizeof (findbuf), 
&cSearch, OL); 


do { 
VioWrtTTY(findbuf.achName, findbuf.cchName, 0); 
VioWrtTTY("\r\n", 2, 0); /7* cursor to next line a/ 

} 

while (DosFindNext (hdir, /7* handle of directory */ 
&findbuf, /* address of buffer */ 
sizeof(findbuf), 7* length of buffer * 
&cSearch) /* number of files to find */ 
== 0); /* while no error occurs . 
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See Also DosBufReset, DosClose, DosFindClose, DosFindFirst, DosFindFirst2 


Changes DosFindNext returns the same type of structure as requested by the most recent 
call to either DosFindFirst or DosFindFirst2. 


DosFreeResource New 


USHORT DosFreeResource( pvData) 
PVOID pvData; /» pointer to data to free «/ 


The DosFreeResource function frees memory allocated by a previous call to the 
DosGetResource2 function. 


Parameters pvData Points to the buffer to free. This pointer should have been returned by 
a previous call to the DosGetResource2 function. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

See Also DosGetResource, DosGetResource2 

DosFreeSeg Change 


USHORT DosFreeSeg( se/) 
SEL sel; /«{ segment selector »/ 


The DosFreeSeg function frees the specified memory segment. This function 
accepts selectors for memory segments, shared-memory segments, huge-memory 
segments, aliased code segments, and resource segments allocated by Dos- 
GetResource. DosFreeSeg frees a shared-memory segment after the segment is 
freed by the last process accessing it. DosFreeSeg frees the code-segment selec- 
tor for aliased code segments, but the corresponding data-segment selector 
remains valid until it is freed. 


The DosFreeSeg function is a family API function. 


Parameters sel Specifies the segment to free. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
' value, which may be the following: 
ERROR_ACCESS_DENIED 
Comments oe can be issued from ring 2, but the segment to free must be a ring-3 
segment. 


DosFreeSeg should not be used to free resource segments allocated by the Dos- 
GetResource2 function. To free those segments, use the DosFreeResource func- 
tion. 


Restrictions In real mode, the following restriction applies to the DosFreeSeg function: 


m A code-segment selector (created by using the DosCreateCSAlias func- 
tion) and the corresponding data-segment selector are the same. Freeing 
one frees both. 
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Example 


See Also 


Changes 


DosFSAttach 


PSZ pszDevName; 
PSZ pszFSD; 
PBYTE pData; 
USHORT cbData; 
USHORT fsOp; 


This example allocates three segments of memory, then calls the DosFreeSeg 
function to free the memory: 


SEL sel; 
DosAllocHuge(3, 200, &sel, 5, SEG _NONSHARED) ; 


DosFreeSeg (sel) ; 


DosAllocHuge, DosAllocSeg, DosAllocShrSeg, DosCreateCSAlias, 
DosFreeResource, DosGetResource, DosGetResource2 


DosFreeSeg should not be used to free segments allocated by the 
DosGetResource2 function. 


New 
USHORT DosFSAttach( pszDevName, pszFSD, pData, cbData, fsOp, ulReserved) 
/« pointer to device name +/ 
/» pointer to file system »/ 
/» pointer to buffer for file-system arguments «/ 
/« length of argument buffer »/ 
/» attach or detach connection «/ 
/« must be zero «/ 


ULONG u/Reserved; 


Parameters 


Return Value 


The DosFSAttach function attaches or detaches a drive or pseudo-character 
device from a remote file system. 


pszDevName Points to a null-terminated string that specifies the drive letter 
followed by a colon or a pseudo-character device name. If this parameter is a 
pseudo-character device name, the format of the sui is \DEV\filename, where 
filename is a valid MS OS/2 filename. 


pszFSD Points to a null-terminated string that specifies the name of the 
remote file system to attach to or detach from the device specified by the 
pszDevName parameter. » 


pData Points to a buffer that contains the file-system arguments. The meaning 
of the arguments is specific to the file system. The first word of the buffer 
specifies the number of strings it contains; the rest of the buffer contains con- 
tiguous strings. 


cbData Specifies the length (in bytes) of the data buffer. 


fsOp Specifies the type of operation to perform. A value of FS_ATTACH 
attaches a file-system connection. A value of FS_DETACH detaches a file- 
system connection. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ALREADY_ASSIGNED 
ERROR_INVALID_DRIVE 
ERROR_INVALID_FSD_NAME 
ERROR_INVALID_LEVEL 
ERROR_LINVALID_PATH 
ERROR_NOT_ENOUGH_MEMORY 


Comments 


Example 


See Also 


DosFSCtl 
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Drive letters that represent local drives cannot be redirected. 


When a drive is attached to a file system, all requests to that drive are routed to 
the file system. When a drive is detached from a file system, the drive name can 
no longer be used. 


When a pseudo-character device name is attached to a file system, all requests to 
that name are routed to the file system. When a pseudo-character device is 
detached from a file system, the device name can no longer be used unless it 
overlaid the name of an existing device; in this case, the previous device regains 
control. 


This example calls DosFSAttach to attach a LAN server to drive X, and then 


calls DosFSAttach again to detach the LAN server: 


CHAR szShareName[] = { 1, O, /7* number of strings * 
"\\SERVER\SHARE" }; /* name of server and share point */ 
DosFSAttach("X:", "LAN", szShareName, sizeof (szShareName) , 


FS_ATTACH, OL); 


DosFSAttach("X:", "LAN", szShareName, sizeof(szShareName) , 
EFS_DETACH, OL); 
DosFSCtl 


New 


USHORT DosFSCtI( pbData, cbData, pcbData, pbParms, cbParm, pcbParm, usFunct, pszRoute, hf, 
usRouteMethod, ulReserved) 


Parameters 


PBYTE pbData; /» pointer to data buffer »/ 
USHORT cbData; /» buffer length »/ 
PUSHORT pcbData; /« pointer to buffer for actual length »/ 
PBYTE pbParms; /»« pointer to parameter list »/ 
USHORT cbParm; /« size of parameter list »/ 
PUSHORT pcbParm; _/« pointer to buffer for actual length »/ 
~USHORT usFunct; /« function code »/ 
PSZ pszRoute; /« pointer to file-system name »/ 
HFILE hf; /« file or device handle »/ 
USHORT usRouteMethod; /« routing method »/ 
ULONG u/Reservea; /» Must be zero »/ 


The DosFSCtl function is used to call functions provided in a file system that are 
not part of the standard set of I/O functions. 
pbData Points to the buffer that receives data from the nonstandard function. 


cbData Specifies the length (in bytes) of the buffer pointed to by the pbData 
parameter. If this value is not at least as large as the value pointed to by the 
pcbData parameter, the system returns the ERROR_BUFFER_OVERFLOW 
error value and the value pointed to by pcbData will contain the correct length. 


pcebData Points to the variable that receives the actual length of data returned. 
pbParms Points to a list of command-specific parameters. 
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Return Value 


Comments 


See Also 


cbParm _ Specifies the length (in bytes) of the pbParms parameter. If the buffer 
size is insufficient, the error value ERROR_BUFFER_OVERFLOW will is 
returned and pcbParm will contain the size of buffer needed. 


pcbParm Points to the variable that contains the length of the commands 
passed to the function and, on return, contains the length of the commands 
returned by the function. usFunct Specifies a function code specific to the file 
system. This parameter can be one of the following values: 


Value Meaning 

0x0000-0x7FFF Reserved for MS OS/2. 

0x8000-OxBFFF Functions to be handled by local file systems. 
0xC000-OxF FFF Functions to be handled by remote file systems. 


pszRoute Points to the string that contains the name of the file system or the 
path of a file or directory that the operation applies to. 


hf Identifies the file or device. 


usRouteMethod Specifies how the request will be routed. This parameter can 
be one of the following values: ; 


Value Meaning 


FSCTL_.HANDLE Route via the file handle. The pszRoute parameter 
must be NULL, and the Af parameter must be a 
valid file or device handle. 


FSCTL_PATHNAME Route via a path. The Af parameter must be - 1, 
and the pszRoute parameter must be a valid MS 
OS/2 path. 


FSCTL_FSDNAME Route via a file-system name. The Af parameter 
must be - 1 and the pszRoute parameter must point 
to the name of a valid file system. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_INTERRUPT 
ERROR_INVALID_CATEGORY 
ERROR_INVALID_FSD_NAME 
ERROR_LINVALID_FUNCTION 
ERROR_INVALID_HANDLE 
ERROR_INVALID_LEVEL 
ERROR_INVALID_PARAMETER 
ERROR_NOT_SUPPORTED 


A usFunct value of 0x0001 returns new error code information from the file sys- 
tem; a value of 0x0002 returns the maximum size of individual extended attri- 
butes in the first word of the buffer pointed to by pbData and the maximum size 
of the full extended-attribute list in the second word of the buffer. 


DosFSAttach 
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HM DosGetDBCSEv Correction 
USHORT DosGetDBCSEv( cbBuf, pctryc, pchBuf) 


USHORT cbBuf; 


/« |ength of buffer »/ 


PCOUNTRYCODE petryc; /» pointer to structure for country code «/ 


PCHAR pchBuf; 


Parameters 


Return Value 


Comments 


/» pointer to buffer for DBCS information «/ 


The DosGetDBCSEy function retrieves the double-byte character set (DBCS) 
environment vector for the given country code and code-page identifier. 


The DosGetDBCSEy function is a family API function. 


cbBuf Specifies the size (in bytes) of the buffer that receives the DBCS 
environment vector. 


petryc Points to the COUNTRYCODE structure that contains the country 
code and code-page identifier used to retrieve the DBCS environment vector. 
The COUNTRYCODE structure has the following form: 
typedef struct _COUNTRYCODE { 

USHORT country; 


USHORT codepage; 
} COUNTRYCODE ; 


pchBuf Points to the buffer that receives the country-dependent DBCS 
environment vector. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NLS_BAD_TYPE 
ERROR_NLS_NO_COUNTRY_FILE 
ERROR_NLS_NO_CTRY_CODE 
ERROR_NLS_OPEN_FAILED 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_TYPE_NOT_FOUND 


The DBCS environment vector defines the low and high ranges for the DBCS 
lead-byte values. 


The DosGetDBCSEv function copies the information from the country.sys file to 
a buffer. The first two bytes in the environment vector specify the low and high 
values in the range for the DBCS lead-byte values. The last two bytes are both 
set to zero. The form of the information is similar to the following: 


BYTE lowl1, highi; 
BYTE low, high2; 


BYTE lown, highn; 
BYTE O, O; 


If the buffer is too small to hold all of the information, the DosGetDBCSEyv 
function truncates the information. To avoid this, make sure the buffer is at least 
ten bytes long. You can verify that all information has been copied by checking 
the last two bytes to make sure they are zeros. If the structure is larger than the 
information, the function fills any remaining bytes with zeros. 
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Restrictions In real mode, the following restriction applies to the DosGetDBCSEyv function: 
@ There is no method of identifying the boot drive. The system assumes 
that the country.sys file is in the root directory of the current drive. 
See Also DosCaseMap, DosGetCollate, DosGetCp, DosGetCtryInfo, DosSetCp, 
. VioGetCp, VioSetCp 
Corrections The DosGetDBCSEv function returns only the range for the lead byte of the 
character set, not for the range of the trail byte. 
DosGetModHandle Correction 


USHORT DosGetModHandle( pszModName, phMod) 


PSZ pszModName; 
PHMODULE phMod; 


Parameters 


Return Value 


Example 


See Also 


/« pointer to module name «/ 
/« pointer to variable receiving module handle »/ 


The DosGetModHandle function retrieves the handle of a dynamic-link module. 
The DosGetModHandle function is typically used to make sure that a module 
has been loaded into memory. If the module has not been loaded, the function 
returns ERROR_MOD_NOT_FOUND, and the DosLoadModule function must 
be used to load the module. 


pszModName Points to the null-terminated string that specifies the module 
name. This string must be a valid MS OS/2 filename. If it does not specify a 
path and the filename extension, the function appends the default extension 
(.dll) and searches for the dynamic-link module in the directories specified by 
the libpath command in the config.sys file. 


phMod Points to the variable that receives the module handle. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_MOD_NOT_FOUND 


This example calls DosGetModHandle to determine if the dynamic-link module 
mydll.dll is currently in memory. If mydill.dll is not in memory, DosGetMod- 
Handle calls DosLoadModule to load it. It then calls DosGetModName to get 
the full path of the module. (This example is accurate if mydll.dll exists in a 
directory defined by the libpath parameter of the config. sys file.) 

USHORT usError; 


HMODULE hmod; 
CHAR achFailName[128], szModName[128]; 
if (usError = DosGetModHandle("mydll", &hmod)) { 
if (usError == ERROR_MOD_NOT_FOUND 
DosLoadModule(achFailName, sizeof (achFailName), 
"mydl1", &hmod); 


+ 
DosGetModName(hmod, sizeof (szModName), szModName) ; 


DosFreeModule, DosGetModName, DosLoadModule 
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Corrections If the pszModName parameter does not specify a path and the filename exten- 
sion, the DosGetModHandle function appends the default extension (.dll) and 
searches for the dynamic-link module in the directories specified by the libpath 
command in the config.sys file. 


DosGetResource Change 
USHORT DosGetResource( hmod, idType, idName, psel) 
HMODULE hmod; /« module handle »/ 

USHORT idType; /« resource-type identifier »/ 

USHORT idName; /« resource-name identifier »/ 

PSEL psel; /« pointer to variable for resource selector »/ 


The DosGetResource function retrieves the specified resource from a specified 
executable file. The function allocates a segment, copies the resource into the 
segment, and returns the segment selector. A process can use this segment 
selector to access the resource directly. 


This function is included in MS OS/2 version 1.2 for compatibility purposes 
only. All new applications should use the DosGetResource2 function, which 
returns a far pointer to the resource, rather than a selector. 


Parameters hmod Identifies the module that contains the resource. This parameter can be 
either the module handle returned by the DosLoadModule function or NULL 
for the application’s module. 


idType Specifies the type of resource to retrieve. 

idName_ Specifies the name of the resource to retrieve. 

psel Points to the variable that receives the selector of the segment containing 
the resource. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_CANT_FIND_RESOURCE 
ERROR_INVALID_MODULE 
ERROR_INVALID_SELECTOR 


‘Comments The following list describes the predefined types that can be used for the idType 
paraineter : 
Type Meaning 
RT_ACCELTABLE Accelerator tables 
RT_BITMAP Bitmap 
RT_CHARTBL Glyph-to-character tables 
RT_DIALOG Dialog template 
RT_DISPLAYINFO Screen-display information 
RT_DLGINCLUDE Dialog include file. 
RT_FONT Font 


RT_FONTDIR Font directory 


102  DosGetResource 


Type Meaning 
RT_HELPSUBTABLE Help-subtable resource. 


RT_HELPTABLE Help-table resource. 
RT_KEYTBL Key to UGL tables 
RT_MENU Menu template 
RT_MESSAGE Error-message tables 
RT_POINTER Mouse-pointer shape 
RT_RCDATA Binary data 
RT_STRING String tables 
RT_VKEYTBL Key to virtual-key tables 
See Also DosGetResource2, DosLoadModule 
Changes This function is included in MS OS/2, version 1.2, for compatibility purposes 
only. All new applications should use DosGetResource2. 
DosGetResource2 New 
USHORT DosGetResource2( hmod, idType, idName, ppData) 
HMODULE hmod; /« module handle s/ 
USHORT jidType; /» resource-type identifier »/ 
USHORT idName; /«{ resource-name identifier s/ 


PVOID FAR * ppData; /» pointer to variable for resource address »/ 


Parameters 


Return Value 


Comments 


The DosGetResource2 function retrieves a pointer to a resource. 


hmod Identifies the module that contains the resource. This parameter can be 
the module handle returned by the DosLoadModule function or NULL for the 
application’s module. 


idType Specifies the type of resource to retrieve. 
idName _ Specifies the name of the resource to retrieve. 
ppData Points to the variable that receives the pointer to the resource. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_INVALID_MODULETYPE 


The DosGetResource2 function allocates a segment, copies the resource into the 
segment, and returns a pointer to the resource. A process can use this pointer to 
access the resource directly. For compatibility with future versions of MS OS/2, 
this function should be used instead of the DosGetResource function, which 
returns a selector instead of a pointer. 
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The following list describes the predefined types that can be used for the idType 


parameter: 
Type 
RT_ACCELTABLE 
RT_BITMAP 
RT_CHARTBL 
RT_DIALOG 
RT_DISPLAYINFO 
RT_DLGINCLUDE 
RT_FONT 
RT_FONTDIR 
RT_HELPSUBTABLE 
RT_HELPTABLE 
RT_KEYTBL 
RT_MENU 
RT_MESSAGE 
RT_POINTER 
RT_RCDATA 
RT_STRING 
RT_VKEYTBL 


Example 


Meaning 


Accelerator tables 
Bitmap 
Glyph-to-character tables 
Dialog template 
Screen-display information 
Dialog include file. 

Font 

Font directory 
Help-subtable resource. 
Help-table resource. 

Key to UGL tables 
Menu template 
Error-message tables 
Mouse-pointer shape 
Binary data 

String tables 

Key to virtual-key tables 


This example calls DosGetResource?2 to retrieve a resource from the 


application’s module, and then the calls DosFreeResource to free the memory 


used by the resource: 


PBYTE pResource; 


if (!DosGetResource2 (NULL, 


RT_MENU 
IDM_MENU, 
&pResource)) { 


DosFreeResource (pResource) ; 


See Also 


M DosGetVersion 


/* loads from application's module */ 

* gets a menu resource a/ 
/* ID of the menu to get */ 
/* pointer address */ 


/* frees resource a/ 


DosFreeResource, DosGetResource, DosLoadModule 


Correction 


USHORT DosGetVersion( pusVersion) 
PUSHORT pusVersion; 


/« pointer to variable receiving version number »+/ 


The DosGetVersion function retrieves version number of the operating system. 
For MS OS/2, version 1.1, both the major and minor version numbers are 10. 
For MS OS/2, version 1.2, the minor version number is 20. 


The DosGetVersion function is a family API function. 
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Parameters pusVersion Points to the variable that receives the version number. The high- 
order byte is set to the major version number; the low-order byte is set to the 
minor version number. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

Example This example retrieves and displays the major and minor version number: 
USHORT usVersion; . 
CHAR ch; 


DosGetVersion (&usVersion) ; 
ch = (HIBYTE(usVersion) / 10) + 'O'; /* gets maj. version number */ 


VioWrtTTY ("You are using MS OS/2 version ", 30, 0); 
VioWrtTTY(&ch, 1, 0); 
VioWrtTTY(".", 1, O); 


ch = (LOBYTE (usVersion) / 10) + '0'; /* gets min. version number */ 
VioWrtTTY (&ch, 1, 0); 
VioWrtTTY("\r\n", 2, 0); 


See Also DosQSysInfo 


Corrections The example incorrectly retrieved the minor version number, instead of the 
major version number. It has been changed to show how to get and display both 
major and minor version numbers. 


DosLoadModule Correction 
USHORT DosLoadModule( pszFaiiName, cbFileName, pszModName, pro’ ) 

PSZ pszFailName; /« pointer to buffer for name if failure »/ 

USHORT cbFileName; /« length of buffer for name if failure »/ 

PSZ pszModName; /« pointer to module name »/ 


PHMODULE phmod; /« pointer to variable for module handle «/ 


The DosLoadModule function loads a dynamic-link module and returns a handle 
for the module. You can use the module handle to retrieve the entry addresses 
of procedures in the module and to retrieve information about the module. 


Parameters pszFailName _ Points to the buffer that receives a null-terminated string. The 
DosLoadModule function copies a string to the buffer only if the function fails 
to load the module. The string identifies the dynamic-link module responsible for 
the failure. This module may be other than the one specified in the pszModName 
parameter if the specified module links to other dynamic-link modules. 


cbFileName Specifies the length (in bytes) of the buffer pointed to by the 
pszFailName parameter. 


pszModName Points to the null-terminated string that specifies the module 
name. This string must be a valid MS OS/2 filename. If it does not specify a 
path and the filename extension, the function appends the default extension 
(.dll) and searches for the dynamic-link module in the directories specified by 
the libpath command in the config.sys file. 


phmod Points to the variable that receives the handle of the dynamic-link 
module. 


Return Value 


Comments 


Example 


See Also 


Corrections 


DosMakePipe 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_FORMAT 
ERROR_FILE_NOT_FOUND 
ERROR_INTERRUPT 
ERROR_INVALID_NAME 
ERROR_NOT_ENOUGH_MEMORY 


The DosLoadModule function loads only MS OS/2 dynamic-link modules. 
Attempts to load other executable files (such as MS-DOS executable files) 
results in an error. 


This example calls the DosLoadModule function to load the dynamic-link 
module ghdil.dil. This example then calls the DosGetProcAddr function to 
retrieve the address of the BOXMESSAGE function that is defined in the 
module. After calling the BOXMESSAGE function, the example calls Dos- 
FreeModule to free the dynamic-link module. (This example is accurate if 
ghdll.dll exists in a directory defined by the libpath parameter of the config.sys . 
file, and if ghdll.dll contains the BOXMESSAGE function that uses the Pascal 
calling convention.) 

CHAR achFailName [128]; 


HMODULE hmod; : 
VOID (PASCAL FAR *pfnBoxMsg) (PSZ, BYTE, BYTE, SHANDLE, SHANDLE, BOOL); 


DosLoadModule (achFailNane, /7* failure name buffer a/ 
sizeof (achFailName) , /* size of failure name buffer */ 
“qhdll", /* module name i 


&hmod) ; /* address of handle a/ 
DosGetProcAddr (hmod, “BOXMESSAGE", &pfnBoxMsg) ; 
pfnBoxMsg("Hello World", Ox30, 1, 0, O, FALSE); 
DosFreeModule(hmod) ; 


DosExecPgm, DosFreeModule, DosGetModName, DosGetProcAddr 


If the pszModName parameter does not specify a path and the filename exten- 
sion, DosLoadModule function appends the default extension (.dll) and searches 
for the dynamic-link module in the directories specified by the libpath command 
in the config.sys file. 


Change 


USHORT DosMakePipe( phfRead, phfWrite, cbPipe) 


PHFILE phfReaad; 
PHFILE phfWrite; 
USHORT cbPipe; 


Parameters 


/« pointer to variable for read handle «/ 
/« pointer to variable for write handle «/ 
/« number of bytes reserved for pipe «/ 


The DosMakePipe function creates a pipe. The function creates the pipe, assign- 
ing the specified pipe size to the storage buffer, and also creates handles that the 
process can use to read from and write to the buffer in subsequent calls to the 
DosRead and DosWrite functions. 


phfRead Points to the variable that receives the read handle for the pipe. 


phfWrite Points to the variable that receives the write handle for the pipe. 
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cbPipe Specifies the size (in bytes) to allocate for the storage buffer for this 
pipe. This can be any value up to 65,536 minus the size of the pipe header, 
which is currently 32 bytes. If this parameter is zero, the default buffer size is 
used. (The buffer size is advisory only. MS OS/2 may allocate more or less 
space.) 


Return Value — The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NOT_ENOUGH_MEMORY 
ERROR_TOO_MANY_OPEN_FILES 


Comments Pipes are typically used by a pair of processes. One process creates the pipe and 
passes a handle to the other process. This lets one process write into the pipe 
and the other read from the pipe. Since MS OS/2 provides no permission 
checks on pipes, the cooperating processes must ensure that they do not attempt 
to write to or read from the pipe at the same time. 


When all of a pipe’s handles are closed by using the DosClose function, MS 
OS/2 deletes that pipe. If two processes are communicating by using a pipe and 
the process that is reading the pipe ends, the next call to the DosWrite function 
for that pipe returns the “broken pipe” error value. 


MS OS/2 temporarily blocks any call to the DosWrite function that would write 
more data to the pipe than can fit in the storage buffer. The system removes the 
block as soon as enough data is read from the pipe to make room for the 
remaining unwritten data. 


See Also DosClose, DosDupHandle, DosRead, DosWrite 

Changes The cbPipe parameter is advisory only. The actual buffer space allocated by the 
system may be larger (to a maximum of 65,536 minus the pipe header size) or 
smaller. 


DosMkDir2 New 
USHORT DosMkDir2( pszDir, peaop, ulReserved) 


- PSZ pszDir; /» pointer to directory name »/ 
PEAOP peaop; /« pointer to structure for extended attributes »/ 
ULONG u/Reserved; /« must be zero s/ 


The DosMkDir2 function creates a directory. 


Parameters pszDir  Poiiits to a null-terminated string that specifies a valid MS OS/2 direc- 
tory name. 


peaop Points to the EAOP structure that defines extended attributes for the 
directory. 


The EAOP structure has the following form: 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value 


Comments 


See Also 


DosMonReg 
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ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_EA_LIST_INCONSISTENT 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_EA_NAME 
ERROR_PATH_NOT_FOUND 


Prior to the function call, the fpFEAList field of the EAOP structure should be 
set to point to the buffer that contains the relevant list of extended attributes. 


If the peaop parameter is NULL, no extended attributes are defined for the 
directory. 


If an error occurs during the creation of the extended attributes, the oError field 
of the EAOP structure will contain the offset within the list where the error 
occurred. 


DosMkDir 


Change 


USHORT DosMonReg(hmon, pbinBuf, pbOutBuf, fPosition, usindex) 


HMONITOR hmon; 
PBYTE pbinBuf, 

PBYTE pbOutBuf; 
USHORT fPosition; 
USHORT us/ndex; 


Parameters 


/»« monitor handle to register »/ 
/» pointer to structure for input buffer —«/ 
/« pointer to structure for output buffer +/ 
/« position flag »/ 
/s index a/ 


The DosMonReg function registers a monitor by placing it in a chain of other 
monitors for the same device. Each monitor receives input from or sends output 
to the device in the order in which it appears in the chain. 


hmon Identifies the monitor to register. This handle must have been created 
previously by using the DosMonOpen function. 


pbInBuf Points to the MONIN structure that receives data from the device 
driver or from the previous monitor in the chain. The MONIN structure has the 
following form: 


typedef struct _MONIN { 
USHORT cb; 
BYTE abReserved [18]; 
BYTE bBuffer [108]; 

} MONIN; 


pbOutBuf Points to the MONOUT structure that receives data for the next 
monitor in the chain. The MONOUT structure has the following form: 


typedef struct _MONOUT { 
USHORT cb; 
BYTE abReserved [18]; 
BYTE abBuffer [108]; 
} MONOUT; 
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Return Value 


fPosition Specifies the position of the monitor in the chain of input and out- 
put. This parameter can be one of the following values: 


Value Meaning 

MONITOR_BEGIN Place the monitor at the beginning of the chain, 
ahead of any other monitors in the chain. 

MONITOR_DEFAULT Place the monitor anywhere in the chain. 

MONITOR_END Place the monitor at the end of the chain. 


Any of the {Position values may be combined with MONITOR_SPECIAL by 
using the OR operator to allow the monitor to continue to receive data even if 
the device is disabled or another monitor further down the chain is blocked. If 
the MONITOR_SPECIAL constant is not set, no monitors will receive input 
when the device driver is disabled or any monitor is blocked. 


usIndex Specifies a device-specific value. If the device is the keyboard, 
usIndex specifies the ID for the screen group to monitor. If no screen-group 
number is available (the monitor is detached), the ID of the current foreground 
screen group can be obtained by calling DosGetInfoSeg. (The current fore- 
ground screen group is the group that most recently called KbdCharIn.) 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MON_BUFFER_TOO_SMALL 
ERROR_MON_LINVALID_HANDLE 
ERROR_MON_INVALID_PARMS 
ERROR_NOT_ENOUGH_MEMORY 


Comments The MONIN and MONOUT structures must be in the same segment. 

See Also DosGetInfoSeg, DosMonClose, DosMonOpen, DosMonRead, DosMonWrite, 
KbdCharIn 

Changes A new value, MONITOR_SPECIAL, can be combined with any other position 
value for the fPosition parameter. This constant lets a monitor receive input even 
if the device is disabled or another monitor in the chain is blocked. 

DosOpen Change 

USHORT DosOpen( pszFileName, phf, pusAction, ulFileSize, usAttribute, fsOpenFlags, fsOpenMode, 

ulReserved) 

PSZ pszFileName; /« pointer to filename »/ 

PHFILE phf; /» pointer to variable for file handle »/ 

PUSHORT pusAction; /» pointer to variable for action taken »/ 

ULONG JlFileSize; /« file size if created or truncated »/ 

USHORT usAttribute; /« file attribute »/ 

USHORT fsOpenFlags; /« action taken if file exists/does not exist «/ 

USHORT fsOpenMode; /« open mode of file »/ 

ULONG ul/Reserved; /« must be zero »/ 


The DosOpen function opens an existing file or creates a new file. This function 
returns a handle that can be used to read from and write to the file, as well as to 


Parameters 


DosOpen 
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retrieve information about the file. The DosOpen function can also be used to 


open a device or a named pipe. 


The DosOpen function is a family API function. 


pszFileName Points to the null-terminated string that specifies the name of 
the file to be opened. The string must be a valid MS OS/2 filename and must not 


contain wildcard characters. 


phf Points to the variable that receives the handle of the opened file. 


pusAction Points to the variable receiving the value that specifies the action 
taken by the DosOpen function. If DosOpen fails, this value has no meaning. 


Otherwise, it is one of the following values: 


Value Meaning 

FILE_CREATED File was created. 
FILE_EXISTED File already existed. 
FILE_TRUNCATED File existed and was truncated. 


ulFileSize Specifies the file’s new size (in bytes). This parameter applies only 
if the file is created or truncated. The size specification has no effect on a file 


that is opened only for reading. 


usAttribute Specifies the file attributes. This parameter can be a combination 


of the following values: 


Value Meaning 

FILELNORMAL File can be read from or written to. 

FILELREADONLY File can be read from, but not written to. 

FILE_LHIDDEN File is hidden and does not appear in a directory 
listing. 

FILE_SYSTEM File is a system file. 

FILE_LARCHIVED File has been archived. 


File attributes apply only if the file is created. 


fsOpenFlags Specifies the action to take both when the file exists and when it 
does not exist. This parameter may be one of the following values: 


Value 


FILE_CREATE 

FILE_OPEN 

FILE_OPEN | FILE_CREATE 
FILE_LTRUNCATE 


FILE_TRUNCATE | FILE_.CREATE 


Meaning 


Create a new file; fail if the file 
already exists. 


Open an existing file; fail if the 
file does not exist. 


Open an existing file or create the 
file if it does not exist. 


Open an existing file and change 
to a given size. 


Open an existing file and truncate 
it, or create the file if it does not 
exist. 
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fsOpenMode Specifies the modes with which to open the file. It consists of 
one access mode and one share mode. The other values are optional and can be 
given in any combination: 


Value 


OPEN_ACCESS_READONLY 


OPEN_ACCESS_READWRITE 


OPEN_ACCESS_WRITEONLY 


OPEN_SHARE_DEN YNONE 


OPEN_SHARE_DENYREAD 


OPEN_SHARE_DEN YREADWRITE 


OPEN_SHARE_DENYWRITE 


OPEN_FLAGS_DASD 


OPEN_FLAGS_FAIL_ON_ERROR 


Meaning 


Data can be read from the file but 
not written to it. 


Data can be read from or written 
to the file. 


Data can be written to the file but 
not read from it. 


Other processes can open the file 
for any access: read-only, write- 
only, or read-write. 


Other processes can open the file 
for write-only access but they can- 
not open it for read-only or read- 
write access. 


The current process has exclusive 
access to the file. The file cannot 

be opened by any process (includ- 
ing the current process). 


Other processes can open the file 
for read-only access but they can- 
not open it for write-only or 
read-write access. 


The file handle represents a physi- 
cal drive that has been opened for 
direct access. (The pszFileName 
parameter must specify a drive 
name.) The DosDevIOCtl func- 
tion can be used with this file han- 
dle to bypass the file system and 
to access the sectors of the drive 
directly. 


Any function that uses the file 
handle returns immediately with 
an error value if there is an I/O 
error—for example, when the 
drive door is open or a sector is 
missing. If this value is not 
specified, the system passes the 
error to the system critical-error 
handler, which then reports the 
error to the user with a hard-error 
popup. The fail-on-error flag is 
not inherited by child processes. 


The fail-on-error flag applies to all 
functions that use the file handle, 
with the exception of the Dos- 
DevIOCtl function. 
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Value Meaning 


OPEN_FLAGS_NOINHERIT The file handle is not available to 
any child process started by the 
current process. If this value is 
not specified, any child process 
started by the current process may 
use the file handle. 


OPEN_FLAGS_WRITE_THROUGH This flag applies to functions, 
such as DosWrite, that write data 
to the file. If this value is 
specified, the system writes data 
to the device before the given 
function returns. Otherwise, the 
system may store the data in an _ 
internal file buffer and write the 
data to the device only when the . 
buffer is full or the file is closed. 


OPEN_FLAGS_NO_LOCALITY There is no specific information 
regarding the locality of reference 
(the degree of randomness with 
which the file is accessed). 


OPEN_FLAGS_SEQUENTIAL The file is accessed sequentially. 
OPEN_FLAGS_RANDOM The file is accessed randomly. 


OPEN_-FLAGS_.RANDOMSEQUENTIAL The file is accessed randomly, but 
that there is a degree of sequential 
I/O within that random access. 
For example, this flag is specified 
if large blocks of data are to be 
read or written at random loca- 
tions in the file. 


OPEN_FLAGS_NO_CACHE The disk drive should not cache 
data in I/O operations on this file. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_CANNOT_MAKE 
ERROR_DISK_FULL 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_INVALID_ACCESS 
ERROR_INVALID_PARAMETER 
ERROR_NOT_DOS_DISK 
ERROR_OPEN_FAILED 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 
ERROR_TOO_MANY_OPEN_FILES 
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Comments 


Restrictions 


Example 


See Also 


Changes 


The ERROR_ACCESS_DENIED value is returned if you try to open a file in a 
mode that is incompatible with the file’s current access and sharing modes—for 
example, if you attempt to open a read-only file for writing. 


The ERROR_SHARING_VIOLATION value is returned if some other process 
has opened the file with a sharing method that denies the type of access you 
have requested. 


Once the file is opened, the DosSetFHandState function can be used to change 
the OPEN_FLAGS_FAIL_ON_ERROR, OPEN_FLAGS_NOINHERIT, and 
OPEN_FLAGS_WRITE_THROUGH flags specified in fsOpenMode. 


MS OS/2 does not provide a built-in method to inform a child process that it has 
inherited a given file handle. The parent process must pass this information to a 
child process. If the file is created without the OPEN_FLAGS_NOINHERIT 
flag, and the parent process terminates without closing the file, the file will 
remain open until all child processes have terminated. 


In real mode, the following restriction applies to the DosOpen function: 


m Only the access modes and the OPEN_FLAGS_DASD flag can be 
specified for the fsOpenMode parameter. 


This example calls the DosOpen function to create a file abc that is 100 bytes 
long and open it for write-only access. The fsOpenFlags parameter is set to 
FILE.CREATE so that DosOpen will return an error if the file already exists. 


HFILE hf; 

USHORT usAction; 

DosOpen ("abe", /* filename to open * 
&hE, 7* address of file handle */ 
&usAction, /* action taken * 
100L, /* size of new file */ 
FILE_NORMAL, /7* file attribute a/ 
FILE_CREATE, /* create the file s/ 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, /* open mode a/ 
OL) ; /* reserved */ 


DosBufReset, DosClose, DosDevIOCtl, DosDupHandle, DosQFHandState, 
DosQFileInfo, DosQFileMode, DosQFSInfo, DosSetFHandState, DosSet- 
FileMode, DosWrite 


The following constants are new for the fsOpenMode parameter: 
Value Meaning 


OPEN_FLAGS_NO_LOCALITY There is no specific information 
regarding the locality of reference 
(the degree of randomness with 
which the file is accessed). 


OPEN_FLAGS_SEQUENTIAL The file is accessed sequentially. 
OPEN_FLAGS_RANDOM The file is accessed randomly. 


OPEN_FLAGS_RANDOMSEQUENTIAL The file is accessed randomly, but 
that there is a degree of sequential 
I/O within that random access. 
For example, this flag is specified 
if large blocks of data are to be 
read or written at random loca- 
tions in the file. 


Corrections 


DosOpen2 
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Value Meaning 


OPEN_FLAGS_NO_CACHE The disk drive should not cache 
data in I/O operations on this file. 


The comments incorrectly stated that ERROR_ACCESS_DENIED would be 
returned if another process had previously opened the file in an incompatible 
mode. The correct error code is ERROR_SHARING_VIOLATION. 


New 


USHORT DosOpen2( pszFileName, phfHand, pusAction, ulFileSize, usAttribute, usOpenFlags, 


ulOpenMode, peaop, u/Reserved) 


PSZ pszFileName; /« pointer to filename s/f 
PHFILE phfHand; /« pointer to variable for file handle »/ 
PUSHORT pusAction; /« pointer to variable for action taken »/ 
ULONG ulFileSize; /« file size if created or truncated »/ 
USHORT usAitribute; /s file attribute »/ 
USHORT usOpenFlags; /« action if file exists/does not exist »/ 
ULONG u/OpenMode; /« open mode of file »/ 


PEAOP peaop; 
ULONG ul/Reserved; 


Parameters 


/« pointer to structure for extended attributes «/ 
/« must be zero »/ 


The DosOpenz2 function opens an existing file or creates a new file. This func- 
tion returns a handle that can be used to read from and write to the file, as well 
as to retrieve information about the file. 


For compatibility with future versions of MS OS/2, the DosOpenz2 function 
should be used instead of the DosOpen function. 


pszFileName Points to the null-terminated string that specifies the name of 
the file to be opened. The string must be a valid MS OS/2 filename and must not 
contain wildcard characters. 


phfHand Points to the variable that receives the handle of the opened file. 


pusAction Points to the variable receiving the value that specifies the action 
taken by the DosOpenz2 function. If DosOpen2 fails, this value has no meaning. 
Otherwise, it is one of the following values: 


Value Meaning 

FILE_CREATED File was created. 
FILE_EXISTED File already existed. 
FILE_TRUNCATED File existed and was truncated. 


ulFileSize Specifies the file’s new size (in bytes). The size specification has no 
effect on a file that is opened only for reading. 


usAttribute Specifies the file attributes. This parameter can be a combination 
of the following values: 


Value Meaning 
FILE_LNORMAL File can be read from or written to. 
FILE_L_READONLY File can be read from, but not written to. 
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Value Meaning 

FILE_HIDDEN File is hidden and does not appear in a directory 
listing. 

FILE_SYSTEM File is a system file. 

FILE_ARCHIVED File has been archived. 


File attributes apply only if the file is created. 


usOpenFlags Specifies the action to take both when the file exists and when it 
does not exist. This parameter can be one of the following values: 


Value Meaning 

FILE_CREATE Create a new file; fail if the file 
already exists. 

FILE_OPEN Open an existing file; fail if the 
file does not exist. 

FILE_OPEN | FILE_CREATE Open an existing file or create the 
file if it does not exist. 

FILE_TRUNCATE Open an existing file and change 
its size to a given size. 

FILE_TRUNCATE | FILE_CREATE Open an existing file and truncate 
it, or create the file if it does not 
exist. 


ulOpenMode __ Specifies the modes with which to open the file. This parameter 
consists of one access mode and one share mode. All other values are optional; 
one locality mode can be specified, and the others can be given in any combina- 


tion: 

Value Meaning 

OPEN_ACCESS_READONLY Data can be read from the file but 
not written to it. 

OPEN_ACCESS_READWRITE Data can be read from or written 
to the file. 

OPEN_ACCESS_WRITEONLY Data can be written to the file but 
not read from it. 

OPEN_SHARE.DENYNONE Other processes can open the file 


for any access: read-only, write- 
only, or read-write. 


OPEN_SHARE_DENYREAD Other processes can open the file 
for write-only access but they can- 
not open it for read-only or read- 
write access. 


OPEN_SHARE_DENYREADWRITE The current process has exclusive 
access to the file. No process 
(including the current process) 
can be open the file. 


OPEN_SHARE_DENYWRITE Other processes can open the file 
for read-only access but cannot 
open it for write-only or read- 
write access. 


Value 


OPEN_FLAGS_DASD 


OPEN_FLAGS_FAIL_ON_ERROR 


OPEN_FLAGS_NOINHERIT 


OPEN_FLAGS_WRITE_THROUGH 


OPEN_FLAGS_NO_LOCALITY 


OPEN_FLAGS_SEQUENTIAL 
OPEN_FLAGS_RANDOM 


DosOpen2 


Meaning 


The file handle represents a physi- 
cal drive that has been opened for 
direct access. (The pszFileName 
parameter must specify a drive 
name.) The DosDevIOCtl func- 
tion can be used with this file han- 
dle to bypass the file system and 
to access the sectors of the drive 
directly. 


Any function that uses the file 
handle returns immediately with 
an error value if there is an I/O 
error—for example, when the 
drive door is open or a sector is 
missing. If this value is not 
specified, the system passes the 
error to the system critical-error 
handler, which then reports the 
error to the user with a hard-error 
popup. The fail-on-error flag is 
not inherited by child processes. 


The fail-on-error flag applies to all 
functions that use the file handle, 
with the exception of the Dos- 
DevIOCtl function. 


The file handle is not available to 
any child process started by the 
current process. If this value is 
not specified, any child process 
started by the current process can 
use the file handle. 


This flag applies to functions (for 
example, DosWrite) that write 
data to the file. If this value is 
specified, the system writes data 
to the device before the given 
function returns. Otherwise, the 
system can store the data in a 
buffer and write the data to the 
device only when the buffer is full 
or the file is closed. 


There is no specific information 
regarding the locality of reference 
(the degree of randomness with 
which the file is accessed). 


The file is accessed sequentially. 


The file is accessed randomly. 
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Value Meaning 


OPEN_FLAGS_RANDOMSEQUENTIAL The file is accessed randomly, but 
that there is a degree of sequential 
I/O within that random access. 
For example, this flag would be 
specified if large blocks of data 
were to be read or written at ran- 
dom locations in the file. 


OPEN_FLAGS_NO_CACHE The disk driver should not cache 
data in I/O operations on this file. 


peaop Points to an EAOP structure that defines extended attributes for the 
file. If this value is NULL, the file will not use extended attributes. Before you 
call the DosOpenz2 function, the fpFEAList field of the EAOP structure must 
point to a data area where the relevant extended-attribute information is stored. 
The EAOP structure has the following form: 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


_ ulReserved Specifies a reserved value; must be zero. 


Return Value 


Comments 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DISK_FULL 
ERROR_EA_LIST_INCONSISTENT 
ERROR_EA_VALUE_UNSUPPORTABLE 
ERROR_FILE_NOT_FOUND 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_ACCESS 
ERROR_INVALID_EA_NAME 

~ ERROR_INVALID_PARAMETER 
ERROR_OPEN_FAILED 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 
ERROR_TOO_MANY_OPEN_FILES 


The read/write pointer is initially set at the first byte of the file. 


The ulFileSize parameter affects the size of the file only when it is created, trun- 
cated, or replaced. The value specified for this parameter is the recommended 
ae size. The file can be opened even if allocation of the full amount of bytes 
ails. ; 


The value of the usOpenFlags parameter provides a disk-access mechanism that 
is independent of the file system. When this value is used, the DosOpen2 func- 


‘tion returns a handle to the calling process that represents the physical drive as a 


file. In order to prevent other processes from accessing the disk, the calling pro- 
cess must also issue a DosDevIOCtl DSK_LOCKDRIVE subcall, which requires 
the file handle returned by the DosOpen2 function for the physical drive. 


See Also 
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Extended attributes that require contiguous disk space may cause the function to 
fail if the file system is unable to allocate contiguous space. 


DosOpenz2 sets extended attributes when a file is created, replaced, or truncated. 
Extended attributes are ordinarily set when a file is opened for reading. When a 
file is replaced, the extended attributes are also replaced. Extended attributes are 
discarded if the peaop parameter is NULL. 


The pszFileName parameter cannot point to a volume label, because volume 
labels cannot be opened. 


Any sharing restrictions placed on a file when it is opened are removed when it 
is closed. When a file is inherited by a child process, all sharing and access res- 
trictions are also inherited. 


The DosOpen2 function opens the client end of a named pipe and returns a han- 
dle of the pipe. The pipe must be in “listen” state for the open operation to 
succeed; otherwise the open operation fails and the ERROR_PIPE_BUSY error 
value is returned. Until a given instance of a named pipe has been closed by a 
client, that same instance cannot be opened by another client; however, the 
opening process can duplicate the open handle as many times as required. The 
access and sharing modes specified when a pipe is opened must be consistent 
with the modes specified in the call to the DosMakeNmPipe function. Pipes are 
always opened with the pipe-specific states set to lock read and write operations 
and are read as a byte stream. 


DosClose, DosDevIOCtl, DosDupHandle, DosMakeNmPipe, DosOpen, 
DosSetFHandState, DosSetFileInfo 


DosQFHandState Change 
USHORT DosQFHandState ( hf, pfsOpenMode) 


HFILE Af; 


/« file handle »/ 


PUSHORT pfsOpenMode; /« pointer to variable for file-handle state »/ 


- Parameters 


The DosQFHandState function retrieves the state of the specified file handle. 
The file-handle state indicates whether the file may be read from or written to 
and whether it may be opened for reading or writing by other processes. 


The DosQFHandState function is a family API function. 


hf Identifies the file whose file-handle state is to be retrieved. This handle 
must have been previously created by using the DosOpen function.’ 


pfsOpenMode Points to the variable that receives the file-handle state. The 
file-handle state consists of one access mode, one share mode, and optional 
flags. It is identical to the values specified in the fsOpenMode parameter of the 
DosOpen function. Which values are set can be determined by using the AND 
operator to combine the value returned in the pfsOpenMode parameter with one 
or more of the following values: 


Value Meaning 

OPEN_ACCESS_READONLY Data can be read from the file but 
not written to it. 

OPEN_ACCESS_READWRITE Data can be read from or written 


to the file. 


Return Value 


Example 


See Also 


Changes 


118 DosQFHandState 


Value 


OPEN_ACCESS_WRITEONLY 


OPEN_SHARE_DENYNONE 


OPEN_SHARE_DENYREAD 


OPEN_SHARE_DENYREADWRITE 


OPEN_SHARE_DENYWRITE 


OPEN_FLAGS_DASD 


OPEN_FLAGS_FAIL_ON_ERROR 


OPEN_FLAGS_NOINHERIT 


OPEN_FLAGS_WRITE_THROUGH 


OPEN_FLAGS_NO_CACHE 


Meaning 


Data can be written to the file but 
not read from it. 


Other processes can open the file 
for any access: read-only, write- 
only, or read-write. 


Other processes can open the file 
for write-only access but not for 
read-only or read-write access. 


The current process has exclusive 
access to the file. 


Other processes can open the file 
for read-only access but not for 
write-only or read-write access. 


The file handle represents a physi- 
cal drive that has been opened for 
direct access. 


Any function that uses the file 
handle returns immediately with 
an error code if there is an I/O 
error. 


The file handle is private to the 
current process. 


The system writes data to the 
device before the given function 
returns. 


The system does not cache file 
data. 


The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be the following: 
ERROR_INVALID_HANDLE 


This example calls the DosQFHandState function using the handle of a previ- 
ously opened file, and then checks the variable fsOpenMode and reports if the 


file is opened for read/write access: 


HFILE hf; 
USHORT fsOpenMode; 


DosQFHandState(hf, &fsOpenMode) ; 


if (fsOpenMode & OPEN_ACCESS_READWRITE) 


VioWrtTITY("File opened for read/write access\r\n", 35, 0); 
if (fsOpenMode & OPEN_SHARE_DENYREADWRITE) 
VioWrtTTY("File cannot be shared\r\n", 23, 0); 


DosDevIOCtl, DosExecPgm, DosOpen, DosSetFHandState 


The OPEN_FLAGS_NO_CACHE value can be specified for the pfsOpenMode 
parameter. If specified, the system does not cache file data. 


M@ DosQFilelnfo 
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Change 


USHORT Dos@QFileInfo( hf, usinfoLevel, pvinfo, cbinfoBuf) 


HFILE Pf; 


USHORT §usi/nfoLevel; 


PVOID pvinfo; 
USHORT cbinfoBuf; 


Parameters 


/« handle of file about which data sought »/ 


/« level of file data required »/ 
/« pointer to file-data buffer »/ 
/« length of file-data buffer »/ 


The DosQFileInfo function retrieves information about a specific file. The file 
information consists of the date and time the file was created, the date and time 
it was last accessed, the date and time it was last written to, the size of the file, 
and its attributes. It can also be used to return information about the extended 
attributes used for a file. 


The file information is based on the most recent call to the DosClose or the 
DosBufReset function. 


The DosQFileInfo function is a family API function. 


hf Identifies the file about which information is to be retrieved. This handle 
must have been created by using the DosOpen function. 


usInfoLevel Specifies the level of file information required. It may — one of 
the following values: 


Value Meaning 


FILE_INFO_1 Level-1 information request. This will return a 
FILESTATUS structure. Any time and data fields 
in the structure that the file-system device does not 
support are set to zero. 


FILE_INFO_2 Level-2 information request. This will return a 
FILESTATUS2 structure, which contains the same 
information as FILESTATUS plus the size of the 
structure used by the FILE_INFO_3 value (for MS 
OS/2 version 1.2, this size cannot exceed 65,535 
bytes). 


FILE_INFO_3 Level-3 information request. This will return an 
EAOP structure that contains a subset of the file’s 
extended-attribute information. 


pvInfo Points to the structure that receives the file information. This structure | 
will be FILESTATUS for FILE_INFO_1 information, FILESTATUS2 for 
FILE_INFO_2 information, and EAOP for FILE_INFO_3 information. 


The FILESTATUS structure has the following form: 


typedef struct _FILESTATUS { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
FDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 
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Return Value 


Comments 


Example 


The FILESTATUS2 structure has the following form: 


typedef struct _FILESTATUS2 { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
EDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 
USHORT cbList; 

} FILESTATUS2; 


The EAOP structure has the following form: . 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbInfoBuf Specifies the length (in bytes) of the buffer that receives the file 
information. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_EA_NAME 
ERROR_EA_LIST_INCONSISTENT 
ERROR_BUFFER_OVERFLOW 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_INVALID_HANDLE 
ERROR_LINVALID_LEVEL 


Prior to the function being called, the fpFEAlist field in the EAOP structure 
should be initialized so that it points to the FEALIST structure that contains the 
relevant FEA structure. The cbList field in the FEALIST structure is valid, giv- 
ing the size of the FEA structure. 


If the FEALIST structure is not large enough to hold the returned information 
(indicated by ERROR_BUFFER_OVERFLOW), ecbList will still be valid, 
assuming there is at least enough space for it. Its value will be the size of the 
entire set of extended attributes for the file, even if only a subset of attributes 
was requested. 


This example opens the file abc, calls the DosQFileInfo function to retrieve the 
current allocated size, and then calls the DosNewSize function to increase the 
file’s size by 1K: 


HFILE hf; 

USHORT usAction; 

FILESTATUS fstsFile; 

DosOpen("abc", &hf, &usAction, OL, FILE _NORMAL, 
FILE_OPEN | FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, OL); 


DosQFileInfo (hf, /* file handle */ 
FILE_INFO_1, /* level of information */ 
&fstsFile, 7* address of file-data buffer */ 
sizeof (fstsFile)); /* size of data buffer * 


DosNewSize(hf, fstsFile.cbFileAlloc + 1024L); 
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See Also DosBufReset, DosClose, DosNewSize, DosOpen, DosQFileMode, 
DosQPathInfo, DosSetFileInfo 
Changes Parameters and structures for FILELINFO_2 and FILE_INFO_2 information 


have been added. The type of the pvInfo parameter has changed from 
PFILESTATUS to PVOID because one of three structures can be used for this 


parameter. 

DosQFSAttach New 
USHORT DosQFSAttach( pszDev, usOrdinal, usinfoLevel, pFSAttBuf, pcbAttBuf, ulReserved) 

PSZ pszDev; /« pointer to drive or device »/ 

USHORT usOrdinal; /« index to drive or device »/ 

USHORT usinfoLevel; /« level of information »/ 

PBYTE pFSAttBuf, /« pointer to structure for file-system attributes »/ 

PUSHORT pcbAttBuf; /»« pointer to structure length »/ 

ULONG u/Reserved; /»« must be zero »/ 


The DosQFSAttach function queries information about an attached remote file 
system or a local file system. The function can also query information about a 
character device or pseudo-character device attached to a local or remote file 

~ system. 


Parameters pszDev Points to a null-terminated string that specifies the drive letter fol- 
lowed by a colon or to the name of a character or pseudo-character device. If 
this parameter is a character or pseudo-character device name, the format of the 
string is \DEV\filename, where filename is a valid MS OS/2 filename. 

This parameter is ignored if the usInfoLevel parameter is set to either 
FSAIL_DEVNUMBER or FSAIL_DRVNUMBER. 


usOrdinal Specifies an index into the list of character or pseudo-character 
devices or the set of drives. The first item in the list is always 1. This parameter 
is ignored if the usInfoLevel parameter is set to FSAILLQUERYNAME. 


usInfoLevel Specifies the type of information requested. This parameter can 
be one of the following values: 
Value Meaning 


FSAIL_QUERYNAME _ Returns information about the drive or device 
pointed to by the pszDev parameter. When this value 
is specified, the usOrdinal parameter is ignored. 


FSAIL_DEVNUMBER _ Returns information about the character or pseudo- 
character device specified by the usOrdinal parame- 
ter. When this value is specified, the pstzDev parame- 
ter is ignored. 


FSAIL_DRVNUMBER _ Returns information about the drive specified by the 
usOrdinal parameter. When this value is specified, 
the pszDev parameter is ignored. 
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Return Value 


Comments 


Example 


See Also 


pFSAttBuf Points to the buffer that receives information about the file system. 
The buffer is organized as a FSQBUFFER structure. Because the name fields can 
vary length, however, the structure cannot be used directly to retrieve the data. 
The PFSQBUFFER structure has the following form: 


typedef struct _FSQBUFFER { 
' USHORT iType; 

USHORT cbName; 
UCHAR szName[1]; 
USHORT cbFESDName; 
UCHAR szESDName[1}; 
USHORT cbFSAData; 
UCHAR rgFESAData[1]; 

} FSQBUFFER; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcbAttBuf Points to the variable that receives the length (in bytes) of the 
buffer. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_DRIVE 
ERROR_INVALID_LEVEL 
ERROR_NO_MORE_ITEMS 


The DosQFSAttach function can be used to ensure that the correct file system is 
loaded for a disk. Without this information, there is potential for the data on the 
disk to be destroyed because the wrong file system could be attached to the disk 
by default. 


This example calls DosQFSAttach to get information about drive C, and then 
displays the device and file-system names: 


PSZ psz; 

PUSHORT pcb; 

USHORT cb; 

SEL sel; 

DosAllocSeg(1024, &sel, SEG _NONSHARED); /* allocates buffer &/ 

if (!DosQFSAttach("c:", 0, FSAIL_QUERYNAME, MAKEP(sel, 0), &cb, OL)) 
pcb = MAKEP(sel, 2); /* points to length of device name */ 
psz = MAKEP(sel, 4); /* points to device name a/ 
VioWrtTTY(psz, *pcb, NULL); /* displays device name a/ 
VioWrtTTY("\r\n", 2, OL); 
ps2 += *tpcb + 3; 7* add null char. and name-length var. a/ 
pcb =. (PUSHORT) (psz - 2); /* points to length of name */ 
VioWrtTTY(psz, *pcb, NULL); /* displays file-system name a/ 


: VioWrtTTY("\r\n", 2, OL); 


DosFSAttach, DosQFSInfo 
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@ DosQNmPipelnfo | Change 
USHORT DosQNmPipelnfo( hp, usinfoLevel, pbBuf, cbBuf) 


HPIPE hp; 


/« pipe handle »/ 


USHORT usinfoLevel; /» level of information to retrieve —«/ 


PBYTE pbBuf; 
USHORT cbBuf; 


Parameters 


Return Value 


Comments 


See Also 
Changes 


Corrections 


/» pointer to buffer for information +/ 
/« number of bytes in buffer »/ 


The DosQNmPipelInfo function retrieves information about a named pipe. 


hp Identifies the pipe to read from. 


_usInfoLevel Specifies the level of information to retrieve. Level 1 is miscel- 


laneous information about the pipe. 


pbBuf Points to the buffer that receives the information. For level-1 informa- 
tion, the data is stored in the PIPEINFO structure. The PIPEINFO structure has 
the following form: 


typedef struct _PIPEINFO { 
USHORT cbOut; 
USHORT cbIn; 
BYTE cbMaxInst; 
BYTE ebCurInst; 
BYTE cbName; 
CHAR szName [1]; 
} PIPEINFO; 


cbBuf Specifies the size (in bytes) of the buffer receiving the information. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_LEVEL 
ERROR_LINVALID_PARAMETER 
ERROR_PIPE_NOT_CONNECTED 


For level-1 information, if the pipe name is longer than 255 bytes, zero will be 
returned in the cbName field of the PIPEINFO structure. The full null- 
terminated string that contains the name will be returned in the location 
specified by the szName field. 


DosQNmPHandState, DosQNmPipeSemState 


Pipe names longer than 255 bytes are now supported. For names longer than 255 
bytes, however, zero is returned in the cbName field of the PIPEINFO structure. 


This function returns only level-1 information. Erroneous references to level-2 
information have been removed. 
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MZ DosQNmPipeSemState Correction 
USHORT DosQNmPipeSemState ( hsem, pnmpsmst, cbBuf) 
HSEM hsem; /« semaphore handle »/ 
PPIPESEMSTATE pnmpsmst; /» pointer to buffer receiving information «/ 
USHORT cbBuf; /« buffer size af 


The DosQNmPipeSemState function returns information about all local named 
pipes that are in blocking mode and are associated with a specified system sema- 
phore. 


Parameters hsem Identifies the semaphore that is associated with the named pipe. 


pnmpsmst Points to the PIPESEMSTATE structure that receives the informa- 
tion. The PIPESEMSTATE structure has the following form: 


typedef struct _PIPESEMSTATE { 
BYTE fStatus; 
BYTE fFlag; 
USHORT usKey; 
USHORT usAvail; 
} PIPESEMSTATE ; 


For a full description of these structures, see Chapter 4, “Types, Macros, Struc- 
tures.” 


cbBuf Specifies the length (in bytes) of the structure that receives the informa- 
tion. Programs written in the C language should use the sizeof operator to set 
this parameter. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_SEM_NOT_FOUND 


See Also DosSetNmPipeSem 
Corrections The second parameter has been replaced by a PIPESEMSTATE structure. 
HZ DosQPathinfo | New 
USHORT DosQPathinfo( pszPath, usinfoLevel, pinfoBuf, cbinfoBuf, ulReserved) 
PSZ pszPath; /« pointer to path »/ 
USHORT usinfoLevel; /« level of information »/ 
PBYTE pinfoBuf, /« pointer to buffer for information «/ 
USHORT cbinfoBuf; /« length of information buffer «/ 
ULONG u/Reserved; /« must be zero »/ 


The DosQPathInfo function returns information about a specified file or direc- 
tory. 
The DosQPathInfo function is a family API function. 

Parameters pszPath Points to the null-terminated string that specifies the path of the file 


or directory. Wildcard characters are valid in the path only when the value of the 
usInfoLevel parameter is FIL.QUERYFULLNAME or FIL_NAMEISVALID. 


DosQPathInfo 
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usInfoLevel Specifies the level of information required. This parameter can 


be one of the following values: 


Value Meaning 
FIL_STANDARD Return a FILESTATUS structure. 
FIL_QUER YEASIZE Return a FILESTATUS structure followed by 


a 4-byte value that specifies the buffer size 
needed to retrieve the entire extended attri- 
bute. 


FIL_QUERYEASFROMLIST _ Return extended-attribute information using 


an EAOP structure for the plnfoBuf parame- 


ter. 
FIL_.QUERYFULLNAME Return the fully qualified path of the buffer 


pointed to by the plnfoBuf parameter. When 
this value is specified, the path pointed to by 


the pszPath parameter can contain wildcard 
characters. 


FIL_NAMEISVALID Verify the correctness (according to MS OS/2 


syntax rules) of the path pointed to by the 
pszPath parameter. If the path is incorrect 
(for example, a filename is too long for the 


current file system), an error will be returned. 


The path can contain wildcard characters. 


pInfoBuf Points to the buffer that contains a FILESTATUS or EAOP struc- 
ture. The structure used is determined by the value specified for the usInfoLevel 


parameter. 
The FILESTATUS structure has the following form: 


typedef struct _FILESTATUS { 
FDATE fdateCreation; 
ETIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
FDATE fdateLastWrite; 
ETIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 


The EAOP structure has the following form: 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” | 


cbInfoBuf Specifies the length (in bytes) of the buffer pointed to by the 
pInfoBuf parameter. 


ulReserved Specifies a reserved value; must be zero. 


Return Value 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_EA_LIST_INCONSISTENT 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_EA_NAME 
ERROR_INVALID_LEVEL 
ERROR_PATH_NOT_FOUND 


Comments If the usInfoLevel parameter is FIL.QUERYEASFROMLIST, a subset of the 
extended-attribute information for the file is returned. Prior to the call to the 
DosQPathInfo function, the fpGEAList field of the EAOP structure should 
point to a list that defines the attribute names for which values will be returned, 
and the fpFEAList field should point to a buffer in which the relevant extended- 
attribute list will be returned. 

See Also DosQFileInfo, DosSetPathInfo 

DosRead Correction 

USHORT DosRead( hf, pvBuf, cbBuf, pcbBytesRead) 

HFILE hf; /« file handle »/ 

PVOID pvBuf; /« pointer to buffer receiving data »/ 

USHORT cbButf; /« number of bytes in buffer »/ 


PUSHORT pcbBytesRead; /« pointer to variable for number of bytes read «/ 


Parameters 


Return Value 


Comments 


The DosRead function reads up to a specified number of bytes of data from a 
file into a buffer. The function may read fewer than. the specified number of 
bytes if it reaches the end of the file. 


The DosRead function is a family API function. 

hf Identifies the file to be read. This handle must have been created by using 
the DosOpen function. 

pvBuf Points to the buffer that receives the data. 

cbBuf Specifies the number of bytes to read from the file. 


pcbBytesRead Points to the variable that receives the number of bytes read 
from the file. This parameter is zero if the file pointer is positioned at the end of 
the file prior to the call to the DosRead function. 


. The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 


ERROR_ACCESS_DENIED 

ERROR_BROKEN_PIPE 

ERROR_INVALID_HANDLE 

ERROR_LOCK_VIOLATION 
. ERROR_NOT_DOS_DISK 


The DosRead function does not return an error if the file pointer is at the end of 
the file when the read operation begins. 
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When DosRead is used to read a byte pipe, the pipe must be in byte-read mode, 
an error is returned if the pipe is in message-read mode. All currently available 
data, up to the size requested, is returned. 


For a message pipe in message-read mode, a read operation that is larger than 
the next available message returns only that message, with pcbBytesRead set to 
indicate the size of the returned message. A read operation that is smaller than 
the next available message returns with the number of bytes requested and an 
ERROR_MORE_DATA error code. Subsequent DosRead calls will continue 
reading the message. The DosPeekNmPipe function can be used to determine 
how many bytes are left in the message. 


For a message pipe in byte-read mode, DosRead reads the pipe as if it were a 
byte stream, skipping over message headers. This is the same as reading a byte 
pipe in byte mode. 


When blocking mode is set, the read operation blocks until data is available. In 
this case, the read operation will never return with the pcbBytesRead parameter 
equal to zero except when it has read an end-of-file (EOF) character. Note that 
in message-read mode, messages are always read entirely, except in the case 
where the message is larger than the size specified for the read operation. 


When nonblocking mode is set, the read operation returns with the 
pcbBytesRead parameter equal to zero upon reading the EOF character. An 
error will be returned if no data is available. 


When resuming reading a message after an ERROR_MORE_DATA error 
occurs, the read operation always blocks until the next part of the message can 
be transferred. When nonblocking mode is set, the read operation can return 
with pcbBytesRead equal to zero if, upon attempting to read at the start of a 
message, it determines that no message is available. 


Example This example opens, reads, and displays the file abc: 


BYTE abBuf [512]; 

HFILE hf; 

USHORT usAction, cbBytesRead, cbBytesWritten; 

DosOpen("abc", &hf, G&usAction, OL, FILE _NORMAL, FILE_OPEN, 
OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, OL); 


do { 
DosRead (hf, /* file handle */ 
abBuf, * address of buffer a/ 
sizeof (abBuf), /* size of buffer a/ 
& 


&cbBytesRead) ; address for number of bytes read */ 
DosWrite(1, abBuf, cbhBytesRead, &cbBytesWritten) ; 


} 
while (cbBytesReadq) ; 


See Also DosChgFilePtr, DosOpen, DosPeekNmPipe, DosReadAsync, DosWrite, 
KbdStringIn 
Corrections DosRead can be used to read from a named pipe. The comments have been 


updated to contain the relevant information about reading from a named pipe. 
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M DosReadAsync 


Change 


USHORT DosReadAsync( hf, hsemRam, pusErrCode, pvBuf, cbBuf, pcbBytesRead) 


HFILE hf; /« file handle »/ 
PULONG hsemRam; -/« pointer to RAM semaphore »/ 
PUSHORT pusErrCode; /» pointer to variable for error return code »/ 
PVOID pvBuf; /» pointer to input buffer »/ 
USHORT cbBuf; /« length of input buffer »/ 


PUSHORT pcbBytesRead; /» pointer to variable for number of bytes read «/ 


Parameters 


Return Value 


Comments 


The DosReadAsynce function reads one or more bytes of data from the file 
identified by the kf parameter. The function reads the data asynchronously; that 
is, the function returns immediately to the process that called it but continues to 
copy data to the specified buffer while the process continues. 


hf Identifies the file to be read. This handle must have been previously opened 
by using the DosOpen function. 


hsemRam Points to the RAM semaphore that indicates when the function has 
finished reading the data. 


pusErrCode Points to the variable that receives any error code the function 
generates while reading data. The possible error codes are identical to those 
returned by the DosRead function. 


pvBuf Points to the buffer that receives the data being read. 


cbBuf Specifies the number of bytes to be read from the file identified by the 
hf parameter. 


pcbBytesRead Points to the variable that receives the number of bytes read 
from the file. 


The return value is zero if the function is successful. Otherwise, it is an error . 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_LINVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_DOS_DISK 


The DosReadAsync function reads up to the number of bytes specified in the 
cbBuf parameter, but it may read fewer if it reaches the end of the file. In any 
case, the function copies the number of bytes read to the variable pointed to by 
the pcbBytesRead parameter. The pcbBytesRead parameter is zero if all the bytes 
in the file have been read (that is, the end of file has been reached). 


If the process intends to use the RAM semaphore pointed to by the hsemRam 
parameter to determine when data is available, it must set the semaphore by 
using the DosSemSet function before calling DosReadAsyne. When Dos- 
ReadAsync has read the data, it clears the RAM semaphore. 


The DosReadAsync function carries out the asynchronous operation by creating 
a new thread that reads from the specified file. The function terminates the 
thread when the operation is complete or when an error occurs. 


Example 


See Also 


Changes 
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When DosReadAsync is used to read a byte pipe, the pipe must be in byte-read 
mode; an error is returned if the pipe is in message-read mode. All currently 
available data, up to the size requested, is returned. 


For a message pipe in message-read mode, a read operation that is larger than 
the next available message returns only that message; pcbBytesRead is set to indi- 
cate the size of the message returned. A read operation that is smaller than the 
next available message returns with the number of bytes requested and an 
ERROR_MORE_DATA error code. Subsequent DosReadAsynce calls will con- 
tinue reading the message. DosPeekNmPipe may be used to determine how 
many bytes are left in the message. 


For a message pipe in byte-read mode, DosReadAsync reads the pipe as if it 
were a byte stream, skipping over message headers. This is the same as reading a 
byte pipe in byte mode. 


When blocking mode is set, a read operation blocks until data is available. In 
this case, the read operation will not return with the pcbBytesRead parameter 
equal to zero except when it has read an end-of-file (EOF) character. Note that 
in message-read mode, messages are always read entirely, except in the case 
where the message is larger than the size specified for the read operation. 


When nonblocking mode is set, a read operation returns with pcbBytesRead 
equal to zero upon reading the EOF character. An error will be returned if there 
is no data available. 


When resuming reading a message after am ERROR_MORE_DATA message, 
the read operation always blocks until the next part of the message can be 
transferred. When nonblocking mode is set, the read operation can return with 
pcbByteRead equal to zero if, upon attempting to read at the start of a message, 
it determines that no message is available. 


This example opens the file abc, sets a RAM semaphore, and calls the Dos- 
ReadAsync function to read part of the file. While the file is being read, program 
execution continues until the call to the DosSemWait function, which does not 
return until the DosReadAsync thread completes its work. 


BYTE abBuf[(512]; 

ULONG hReadSemaphore = 0; 

HFILE hf; 

USHORT usAction, cbBytesRead; 

USHORT usReadReturn; 

DosOpen("abc", G&hf, G&usAction, OL, FILE_NORMAL, FILE_OPEN, 
OPEN_ACCESS_READONLY | OPEN _SHARE_DENYNONE, OL); 


DosSemSet (&hReadSemaphore) ; /* sets RAM semaphore */ 

DosReadAsync (hf, /* handle to file */ 
&hReadSemaphore, /* address of semaphore a/ 
&usReadReturn, /* address to store return code */ 
abBuf, /* address of buffer * 
sizeof (abBuf), /* size of buffer */ 
&cbBytesReadg) ; /7* number of bytes read ‘ 


. /* Other processing occurs here. */ 


DosSemWait (&hReadSemaphore, -1L); 


DosOpen, DosPeekNmPipe, DosRead, DosSemSet, DosSemWait, 
DosWriteAsync 


Information about using this function with pipes has been added. 
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| DosReadQueue , Correction 
USHORT DosReadQueue( hqueue, pqresc, pcbElement, ppv, usElement, fWait, pbElemPrty, hsem) 
HQUEUE /hqueue; /» handle of queue to read »/ 
PQUEUERESULT pqresc; /« pointer to structure for PID and request code »/ 
PUSHORT pcbEl/ement; /« pointer to variable for length of element »/ 
PVOID FAR * ppv; /« pointer to buffer for element »/ 
USHORT usElement; /« element number to read »/ 
UCHAR fWait; /« wait/no wait indicator »/ 
PBYTE pbElemPrty; /« pointer to variable for priority of element »/ 
HSEM hsem; /« semaphore handle »/ 


The DosReadQueue function retrieves an element and then removes it from a 
queue. It copies the address of the clement to the supplied pointer and fills a 
structure with information about the element. 


Parameters hqueue Identifies the queue to read. This handle must have been created or 
opened by using the DosCreateQueue or DosOpenQueue function. 


pqresc Points to the QUEUERESULT structure that receives information 
about the request. The QUEUERESULT structure has the following form: 
typedef struct _QUEUERESULT { . 

PID pidProcess; 


USHORT usEventCode; 
} QUEUERESULT; 


pcbElement Points to the variable that receives the length (in bytes) of the 
element. 7 3 


ppv Points to the pointer that receives the address of the element in the 
queue. 


usElement Specifies where to look in the queue for the element. If this 
parameter is 0x0000, the function looks at the beginning of the queue. Other- 
wise, the function assumes the value is an element identifier retrieved by using 
the DosPeekQueue function and looks for the specified element. 


fWait Specifies whether to wait for an element to be placed in the queue, if 
the queue is empty. If this parameter is DCWW_WAIT, the function waits until 
an element is available. If this parameter is DCWW_NOWAIT, the function 
returns immediately with a code that indicates there are no entries in the queue. 


pbElemPrty Points to the variable that receives the priority value specified 
when the element was added to the queue. This is a value in the range 0 through 
15; 15 indicates the highest priority. 


hsem Identifies a semaphore. This value can be the handle of a system sema- 
phore that has been created or opened by using the DosCreateSem or DosOpen- 
Sem function, or it can be the address of a RAM semaphore. This semaphore 
would typically be used in a call to the DosMuxSemWait function to wait until 
the queue has an element. If the fWait aa is DCWW_WATT, hsem is 
ignored. 


DosReallocHuge 131 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_ELEMENT_NOT_EXIST 
ERROR_QUE_EMPTY 
ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_LINVALID_WAIT 
ERROR_QUE_PROC_NOT_OWNED 


Comments If the queue is empty, the DosReadQueue function either returns immediately or 
waits for an element to be written to the queue, depending on the value of the 
fWait parameter. 


Only the process that created the queue can call the DosReadQueue function. 


Example This example reads the queue and waits until an element is received. After the 
element is read and the data processed, the process frees the shared memory 
that was passed to it. This assumes the process writing to the queue created a 
shared-memory segment. For more information, see the DosWriteQueue func- 
tion. 


QUEUERESULT qresc; 
USHORT cbhElement; 
PVOID pv; 

BYTE bElemPrty; 


DosReadQueue (hqueve, /* queue handle */ 
&qresc, * address of result structure */ 
&cbElement, /* receives element number */ 
apy: /* receives data address */ 

/* element number to read */ 
Dewi. WAIT, /* waits until something is written */ 
&bElemPrty, /* receives priority level * 
NULL) ; /* semaphore not needed, since waiting a/ 


. /* Process the data. */ 
DosFreeSeg (SELECTOROF (pv) ); /* frees shared memory */ 


See Also DosCreateQueue, DosMuxSemWait, DosOpenQueue, DosOpenSem, 
DosPeekQueue, DosWriteQueue 


Corrections The description incorrectly stated that the element was copied to the supplied 
buffer. It is the address of the element that is copied to the supplied pointer. No 
data is actually copied; only the pointer to the data is copied. 


DosReallocHuge Change 
USHORT DosReallocHuge ( usNumSeg, usPartialSeg, sel) 

USHORT usNumSeg; /« number of 65,536-byte segments »/ 

USHORT usPartialSeg; /» number of bytes in last segment «/ 

SEL sel; /» segment selector »/ 


The DosReallocHuge function reallocates a fiuse-miemory block. This function 
changes the size of the huge memory to the specified number of 65,536-byte seg- 
ments plus an additional segment of a specified size. 


The DosReallocHuge function is a family API function. 
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Parameters 


Return Value 


Comments 


Restrictions 


See Also 


Changes 


usNumSeg Specifies the number of 65,536-byte segments to allocate. 


usPartialSeg Specifies the number of bytes in the last segment. This number 
can be any value in the range 0 through 65,535. If this number is zero, no addi- 
tional segment is allocated. 


sel Specifies the selector for the huge-memory block to be reallocated. The 
selector must have been created by using the DosAllocHuge function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


The DosReallocHuge function does not change the sharable and discardable 
attributes of the segments in the huge-memory block. If it was originally a shar- 
able or discardable block, it remains a sharable or discardable block. However, 
if DosReallocHuge reallocates a discardable block, it also locks the segments. 
The DosUnlockSeg function must be used to unlock the segments and permit 
discarding. 


_ The huge-memory block cannot be reallocated for a size larger than the max- 


imum specified by the usMaxNumSeg parameter in the original call to the 
DosAllocHuge function. © 


Each segment in the huge-memory block has a unique selector. The selectors are 
consecutive. The sel parameter specifies the value of the first selector; the 
remaining selectors can be computed by adding the selector offset to the first 
selector one or more times—that is, once for the second selector, twice for the 
third, and so on. The selector offset is a multiple of 2, as specified by the shift 
count retrieved by using the DosGetHugeShift function. For example, if the shift 
count is 2, the selector offset is 4 (1 << 2). If the selector offset is 4 and the 
first selector is 6, the second selector is 10, the third is 14, and so on. 


Typically, DosReallocHuge can increase, not decrease, the size of shared huge 
segments. If the shared segment is allocated by the DosAllocHuge function, the 
segment can be decreased in size by setting the fsAttr parameter to 
SEG_SIZEABLE. 


DosReallocHuge can be issued from ring 2, but only ring-3 segments are affected 
by this function. 


In real mode, the following restriction applies to the DosReallocHuge function: 


m= The usPartialSeg parameter is rounded up to the next paragraph (16-byte) 
value. 


DosAllocHuge, DosIreeSeg, DosGetHugeShift, DosLockSeg, DosReallocSex, 
DosUnlockSeg 


Typically, DosReallocHuge can increase, not decrease, the size of shared huge 


- segments. If the shared segment is allocated by the DosAllocHuge function, the 


segment can be decreased in size by setting the fsAttr parameter to 
SEG_SIZEABLE. 


DosReallocHuge can be issued from ring 2, but only ring-3 segments are affected 
by this function. 


™@ DosReallocSeg 
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Change 


USHORT DosReallocSeg( usNewSize, se/) 


USHORT usNewSize; 


SEL sel; 


Parameters 


Return Value 


Comments 


Restrictions 


Example 


See Also 


Changes 


/« new segment size «/ 
/x segment selector «/ 


The DosReallocSeg function reallocates a segment. The function changes the 
size of the segment to the number of bytes specified by the usNewSize parameter. 


The DosReallocSeg function is a family API function. 


usNewSize Specifies the new size (in bytes). The size can be any number from 
0 through 65,535. If it is 0, the function allocates 65,536 bytes. 


sel Specifies the selector of the segment to be reallocated. The selector must 
have been created previously by using DosAllocSeg or DosAllocShrSeg. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_NOT_ENOUGH_MEMORY 


The DosReallocSeg function does not change the sharable and discardable attri- 
butes of the segment. If it was originally a sharable or discardable segment, it 
remains a sharable or discardable segment. If DosReallocSeg reallocates a dis- 
cardable segment, however, it also locks the segment. You must use the Dos- 
UnlockSeg function to unlock the segment and permit discarding. 


If the DosReallocSeg function is used to reallocate a shared segment to a size 
smaller than its original size, the segment must have been created using the 
DosAllocSeg function with the SEG_SIZEABLE attribute set. This request can 
be issued from ring 2 or ring 3; the segment to be reallocated can be a ring-2 or 
a ring-3 segment. 


The DosReallocSeg function cannot be used to reallocate a segment created by 
the DosCreateCSAlias function. 


In real mode, the following restriction applies to the DosReallocSeg function: 


™ The usNewSize parameter is rounded up to the next paragraph (16-byte) 
value. 


This example allocates a segment with 16,000 bytes, and then calls DosReal- 
locSeg to increase the size to 32,000 bytes: 


SEL sel; 
DosAllocSeg(16000, &sel, SEG_NONSHARED) ; /* allocates memory a/ 
DosReallocSeg(32000, sel); /* reallocates memory */ 


DosAllocSeg, DosFreeSeg, DosLockSeg, DosReallocHuge, DosUnlockSeg 


If DosReallocSeg is used to reallocate a shared segment to a size smaller than its 
original size, the segment must have been created using the DosAllocSeg func- 
tion with the SEG_SIZEABLE attribute set. This request can be issued from 
ring 2 or ring 3; the segment to be reallocated can be either a ring-2 or a ring-3 
segment. 
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—H DosSearchPath 


USHORT fsSearch; 
PSZ pszPath; 
PSZ pszFileName; 
PBYTE pbBuf; 


Change 
USHORT DosSearchPath( fsSearch, pszPath, pszFileName, pbBuf, cbBuf) 
/« search flags »/ 
/« pointer to search path or environment variable «/ 
/« pointer to filename »/ 
/« pointer to result buffer »/ 
/« length of result buffer «/ 


USHORT cbBuf; 


Parameters 


The DosSearchPath function searches the specified search path for the given 
filename. The search path is a null-terminated string that consists of a sequence 
of directory paths separated by semicolons (;). The function searches for the 
filename by looking in each directory (one directory at a time) in the order 
given. 


fsSearch Specifies how to interpret the pszPath parameter and whether to 
search the current directory. This parameter can be a combination of the follow- 
ing values: 


Value Meaning 


DSP_ENVIRONMENT The pszPath parameter points to the 
name of an environment variable. The 
function retrieves the value of the 
environment variable from the environ- 
ment segment of the process and uses it 
as the search path. If this value is not 
specified, pszPath points to a string that 
specifies the search path. This value can- 
not be used with the DSP_PATH value. 


DSP_IGNORE_NET_ERR If this value is set, the search ignores any 
network errors encountered during during 
processing and continues to search the 
remainder of the path. If this value is not 
specified, a network error (for example, 
when a server is unavailable) causes the 
search to halt. 


DSP_CUR_DIRECTORY The function searches the current direc- 
tory before it searches the first directory 
in the search path. If this value is not 
specified, the function searches the 
current directory only if it is explicitly 
given in the search path. . 


DSP_PATH The pszPath parameter points to a string 
that specifies the search path. This 
value cannot be used with the 
DSP_LENVIRONMENT value. 


pszPath _ Points to the null-terminated string that specifies the search path. If 
DSP_PATH is specified for the fsSearch parameter, the pszPath parameter 
points to an environment variable. Otherwise, the pszPath parameter points to — 
one or more paths to search. The paths are separated by semicolons (;). 


Return Value 


Comments 


Example 


See Also 
Changes 
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pszFileName Points to a null-terminated string that specifies the filename to 
search for. The string must be a valid MS OS/2 filename and can contain wild- 
card characters. 


pbBuf Points to the buffer that receives the full path name of the file if the 
filename is found. 


cbBuf Specifies the length (in bytes) of the buffer pointed to by the pbBuf 
parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


If DosSearchPath finds a matching filename in any of the directories specified by 
the search path, the function copies the full, null-terminated path name to the 
buffer pointed to by the pbBuf parameter. If the filename pointed to by the 
pszFileName parameter contains wildcard characters, the resulting path name 
will also contain wildcard characters; the DosFindFirst function can be used to 
retrieve the actual filename(s). 


The DosSearchPath function does not check for the validity of filenames. If the 
filename is not valid, the function returns an error, indicating that the file was 
not found. 


This example uses the search path specified by the DPATH environment variable 
to search for the abc.txt filename: 


CHAR szFoundFile[128]; 


DosSearchPath (DSP_ ENVIRONMENT, /* uses environment variable */ 
"DPATH", 7* uses DPATH search path * 
"“abe.txt", /* filename a 
szFoundFile, /* receives resulting filename */ 
sizeof (szFoundFile) ) ; /* length of result buffer 


The following example is identical to the first example if the DPATH variable is 
defined as shown: 


DPATH=c:\sysdir;c:\init 
DosSearchPath (DSP_ PATH, /* uses search path */ 


"co: \\sysdir; c: \\init", /* search path a/ 
“abe.txt" /* filename 7 
szFoundFile, /* receives resulting filename */ 
sizeof (szFoundFile)); /* length of result buffer id 


DosFindFirst, DosScanEny 


' The constants SEARCH_PATH, SEARCH_CUR_DIRECTORY, and 


SEARCH_ENVIRONMENT have been changed to DSP_PATH, 
DSP_CUR_DIRECTORY, and DSP_LENVIRONMENT, respectively. A new 
constant, DSP_LIGNORE_NET_ERR, has been added to allow searches to con- 
tinue when a network drive specified in the path might not be available at the 
time of the search. 


Correction 


USHORT DosSemClear( hsem) 


HSEM hsem; 


/» semaphore handle »/ 


The DosSemClear function clears a system or RAM semaphore that has been 
set by using the DosSemRequest, DosSemSet, or DosSemSetWait function. 
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Parameters 


Return Value 


hsem Identifies the semaphore to clear. This value can be the handle of a sys- 
tem semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 


Comments The DosSemClear function cannot clear a system semaphore that is owned by 
another process unless the semaphore is nonexclusive. 
Example This example uses the DosSemClear function to clear a RAM semaphore and a 
system semaphore: 
ULONG hsem = O; 
HSYSSEM hsys; 
DosSemClear (&hsem) ; /* clears RAM semaphore */ 
DosSemClear (hsys) ; /* clears system semaphore */ 
See Also DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemRequest, Doscem: 
Set, DosSemSetWait, DosSemWait 
Corrections The example incorrectly used the address of the system semaphore rather than 
the handle of the system semaphore. System semaphores require the handle of 
the semaphore; RAM semaphores require the address of the semaphore. 
DosSemRequest Correction 


USHORT DosSemRequest( hsem, TimeOuty 


HSEM hsem; 


LONG /TimeOut; 


Parameters 


Return Value 


/« semaphore handle +/ 
/« time-out «/ 


The DosSemRequest function obtains and sets a semaphore. If no previous 
thread has set the semaphore, DosSemRequest sets the semaphore and returns 
immediately. If the semaphore has already been set by another thread, the func- 
tion waits until a thread clears the semaphore (by using the DosSemClear func- 


tion) or until a time-out occurs. The DosSemRequest function is also used to 


obtain ownership of a system semaphore created with the CSEM_PRIVATE flag 
set (see DosCreateSem). 


hsem Identifies the semaphore to set. This value can be the handle of a sys- 
tem semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


ITimeOut Specifies how long to wait for the semaphore to clear. If the value 
is greater then zero, this parameter specifies the number of milliseconds to wait 
before returning. If the value is SEM_IMMEDIATE_RETURN, the function 
returns immediately. If the value is SEM_INDEFINITE_WAIT, the function 
waits indefinitely. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_SEM_OWNER_DIED 


Comments 


Example 


See Also 


Corrections 


DosSetFileInfo 
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ERROR_SEM_TIMEOUT 
ERROR_TOO_MANY_SEM_REQUESTS 


If DosSemRequest is used to obtain exclusive ownership of a semaphore created 
by another process, it will wait (if [TimeOut is non-zero) until the semaphore is | 
clear, or until the process that currently owns the semaphore closes the sema- 
phore or terminates. If the process owning the semaphore terminates, DosSem- 
Request will return with an error value of ERROR_SEM_OWNER_DIED, how- 
ever ownership will be transferred and the semaphore will be set and can be 
used by the calling process. 


The effects of DosSemRequest are cumulative. If multiple calls to the DosSem- 
Request function set the semaphore, the same number of calls to the DosSem- 
Clear function are required to clear the semaphore. 


If more than one thread has requested to set the semaphore, a thread may have 
to wait through several changes of the semaphore before it continues (depending 
on which thread clears the semaphore and when the system scheduler passes 
control to the thread). As long as the semaphore is set (even if it has been 
cleared and reset since the thread originally called the function), the thread must 
wait. 


The DosSemRequest function can set system or RAM semaphores. A system 
semaphore is initially clear when it is created. A RAM semaphore is clear if its _ 
value is zero. Programs that use RAM semaphores should assign the initial value 
of zero. 


This example uses the DosSemRequest function to create a RAM semaphore. It 
also shows how to set and clear the semaphore. 
ULONG hsem = O; 


DosSemRequest (&hsem, /* address of handle */ 
SEM_INDEFINITE_WAIT) ; /* waits indefinitely */ 


DosSemClear (&hsem) ; -{* clears semaphore */ 


DosCreateSem, DosExitList, DosMuxSemWait, DosOpenSem, DosSemClear, 
DosSemSet, DosSemSetWait, DosSemWait 


DosSemRequest is used not only to set a semaphore once it becomes clear, but 


also to obtain exclusive ownership of a system semaphore created with the 
CSEM_PRIVATE flag. 


Change 


USHORT DosSetFileInfo ( hf, usinfoLevel, pinfoBuf, cbinfoBuf) 


HFILE hf; 


/« handle of file about which data sought «/ 


USHORT usinfoLevel; /« level of file data required al 


PBYTE pinfoBuf; 
USHORT cbinfoBuf; 


/« pointer to file-data buffer «/ 
/« length of file-data buffer »/ 


The DosSetFileInfo function sets information about a specific file. The file infor- 
mation consists of the date and time the file was created, the date and time it 
was last accessed, the date and time it was last written to, the size of the file, 
and its attributes. It can also be used to set extended attributes for a file. 


The DosSetFileInfo function is a family API function. 
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Parameters 


Return Value 


Comments 


hf Identifies the file about which information is to be set. This handle must 
have been created by using the DosOpen function. 


usInfoLevel Specifies the level of file information. This may be one of the fol- 
lowing values: 


Value Meaning 


FILE_INFO_1 Level-1 information request. This uses a 
FILESTATUS structure. Any date and time fields 
in this structure that the file system does not sup- 
port should be set to zero. 


FILE_INFO_2 Level-2 information request. This uses an EAOP 
structure, which contains the file’s extended- 
attribute information. 


pInfoBuf Points to the structure that contains the file information. This struc- 
ture will be FILESTATUS or EAOP, depending on the usInfoLevel parameter. 


The FILESTATUS structure has the following form: 


typedef struct _FILESTATUS { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
EDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
EDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 


The EAOP structure has the following form: 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbInfoBuf Specifies the length (in bytes) of the buffer that contains the file 
information. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_EA_LIST_INCONSISTENT 
ERROR_INVALID_EA_NAME 
ERROR_INVALID_HANDLE 
ERROR_INVALID_LEVEL 


DosSetFileInfo works only for files opened in a mode that allows write access. 


Prior to the function being called, the fpFEAlist field in the EAOP structure 
should be initialized so that it points to the FEALIST structure that contains the 
relevant FEA structure. The cbList field in the FEALIST structure is valid, giv- 
ing the size of the FEA structure. 


A zero value in both the date and time components of a field causes that field to 
be unchanged. For example, if both the fdateLastWrite and ftimeLastWrite 


See Also 


Changes 


DosSetMaxFH 
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fields are zero in the FILESTATUS structure, both attributes of the file remain 
unchanged. If either of these fields are nonzero, both attributes of the file are set 
to the new values. If extended attributes are modified, the file’s last modification 
date and time are changed. 


DosBufReset, DosClose, DosNewSize, DosOpen, DosSetFileMode, 
DosQFileInfo 


The constant FILE_INFO_2 has been added. 


Change 


USHORT DosSetMaxFH( usHandles) 


USHORT usHandles; 


Parameters 


Return Value 


/« number of file handles »/ 


The DosSetMaxFH function sets the maximum number of available file handles 
for the current process and any of its child processes. The number of available 
handles limits the number of files that can be opened at the same time. 


usHandles Specifies the maximum number of file handles provided to the call- 
ing process. The maximum value for this parameter is 32,767; the minimum is 
20. This number must not be smaller than the current number of file handles 
allocated. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH._MEMORY 


Comments This function preserves all currently open file handles. 
There are three handles in use when a process is started—for standard input, 
standard output, and standard error. The number of available handles set by the 
DosSetMaxFH function includes these handles. The DosOpenQueue, KbdOpen 
and MouOpen functions also use these handles. 

See Also DosDupHandle, DosOpen, DosOpenQueue, KbdOpen, MouOpen 

Changes The maximum number of handles has been increased from 255 to 32,767. 

DosSetPathInfo New 

USHORT DosSetPathinfo( pszPathName, usinfoLevel, pinfoBuf, cbinfoBuf, fsOptions, ulReserved) 

PSZ pszPathName; /« pointer to path »/ 

USHORT usinfoLevel; /« level of information »/ 

PBYTE pinfoBuf; /« pointer to buffer for information »/ 

USHORT cbinfoBuf: /» length of information buffer »/ 

USHORT fsOptions; /« options — »/ 

ULONG u/Reserved; /«{ must be zero »/ 


The DosSetPathInfo function sets information for a specified file or directory. 
The DosSetPathInfo function is a family API function. 
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Parameters pszPathName Points to the null-terminated string that specifies the path of 
the file or directory. The string must be a valid MS.OS/2 path. 


usInfoLevel Specifies the level of information to set. This parameter can be 
one of the following values: 


Value Meaning 


FIL_STANDARD Use a FILESTATUS structure. 
FIL_QUERYEASIZE Use an EAOP structure to set extended attributes. 


pInfoBuf _Points to the buffer where path information is stored. The buffer 
contains a FILESTATUS structure for FIL.STANDARD information or an 
EAOP structure for FIL.QUERYEASIZE information. 


The FILESTATUS structure has the following form: 


typedef struct  _FILESTATUS { 
EDATE fdateCreation; 
FTIME ftimeCreation; 
EDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
ETIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbhFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 


The EAOP structure has the following form: | 


typedef struct _EAOP { 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 

} EAOP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbInfoBuf Specifies the length (in bytes) of the buffer pointed to by the 
pInfoBuf parameter. 


fsOptions Specifies one or more options. For MS OS/2, version 1.2, 
DSPI_WRTTHRU is the only available option. The DSPILWRTTHRU option 
means all data, including extended attributes, must be written to the disk before 
the function returns. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
| value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_EA_LIST_INCONSISTENT 
ERROR_FILENAME_EXCED_RANGE 
ERROR_INVALID_EA_NAME 

~* ERROR_INVALID_LEVEL | 
ERROR_PATH_NOT_FOUND 


Comments ' If the DosSetPathInfo, function is used to set extended-attribute information, the 
fpFEAList field of the EAOP structure should point to the FEALIST structure 
that contains the extended attributes. The fpGEAList field of the EAOP struc- 
ture will be ignored. 


See Also 


DosSetPrty 


USHORT fScope; 
USHORT fPrtyClass; 
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DosSetPathInfo fails if another process has the same file or directory. 


A zero value in both the date and time fields of an attribute cause those attri- 
butes to remain unchanged. For example, if both the fdateLastWrite and 
ftimeLastWrite fields of the FILESTATUS structure are zero, both attributes are 
unchanged. If either field is nonzero, both fields are set to the new values. If 
extended attributes are modified, the file’s last modification date and time will be 
changed. 


DosQPathInfo, DosSetFileInfo 


Change 
USHORT DosSetPrty( fScope, fPrtyClass, sChange, id) 
/« scope of change »/ 
/« priority class to set »/ 
/« Change in priority level »/ 


SHORT sChange; 
USHORT id; 


Parameters 


/« process or thread identifier »/ 


The DosSetPrty function sets the scheduling priority of the specified process or 
thread by changing the priority class and/or the priority level. 


Within each class, a thread’s priority level may vary—either through system 
action or through the DosSetPrty function. The system changes a thread’s prior- 
ity level based on that thread’s actions and the overall system activity. 


fScope Specifies the scope of the request. This parameter can be one of the 
following values: 


Value Meaning 

PRTYS_PROCESS Priority for the process and all its threads. 

PRTYS_PROCESSTREE Priority for the process and all its child 
processes. 

PRTYS_THREAD Priority for one thread in the current process. 


fPrtyClass Specifies the priority class of a process or thread. This parameter 
can be one of the following values: 


Value Meaning 
PRTYC_IDLETIME Idle time. 
PRTYC_NOCHANGE No change; leave as is. 
PRTYC_REGULAR Regular. 
PRTYC_FOREGROUND Foreground server. 
PRTYC_TIMECRITICAL Time-critical. 


sChange Specifies the relative change in the current priority level of the pro- 
cess or thread. This parameter can be any value from - 31 through +31, or the 
constants PRTYD_MINIMUM or PRTYD_MAXIMUM, which specify the 
minimum and maximum change allowed. 


id Specifies the process or thread identifier, depending on the value of the 
fScope parameter. If the value is a process identifier, it must be for the calling 
process or a child of the calling process. A value of zero can be used to specify 
the current thread or process. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PCLASS 
ERROR_INVALID_PDELTA 
ERROR_INVALID_PROCID 
ERROR_INVALID_SCOPE 
ERROR_INVALID_THREADID 
ERROR_NOT_DESCENDANT 


Comments The PRTYC_FOREGROUND priority is higher than PRTYC_REGULAR, but 
lower than PRTYC_TIMECRITICAL. PRTYC_FOREGROUND is a static 
priority that is not changed by the system. This allows a thread or process in a 
background screen group to service requests of a foreground process in a timely . 
manner. Because the priority level is static, this priority should be used only 
when absolutely necessary. Indiscriminate use degrades system performance. 


See Also DosEnterCritSec, DosGetInfoSeg, DosGetPrty 

Changes A new value, PRTYC_FOREGROUND, can be specified for fPrtyClass. 
DosSetVec . Correction 
USHORT DosSetVec( usVecNum, pfnFunction, ppfnPrev) 

USHORT usVecNum; /» type of exception »/ 

PFN pfnFunction; /» pointer to function »/ 

PPFN ppfnPrev; /» pointer to variable for previous function's address »/ 


The DosSetVec function installs or removes an exception handler for a specified 
exception. An exception is a program error, such as division by zero, that causes 
the system to pass control to the exception handler. The exception handler is an 
assembly-language routine that corrects errors or cleans up programs before ter- 
minating. The system calls the exception handler whenever the specified excep- 
tion occurs. If a process does not install its own exception handler, the default 
exception handler terminates the process when an exception occurs. 


The DosSetVec function is a family API function. 


Parameters usVecNum _ Specifies the number of the exception vector. This parameter can 
be one of the following values: 

Value Meaning 
VECTOR_DIVIDE_BY_ZERO Division by zero 
VECTOR_EXTENSION_ERROR Processor extension error 
VECTOR_INVALIDOPCODE Invalid operation code (opcode) 
VECTOR_NO_EXTENSION Processor extension not available 
VECTOR_OUTOFBOUNDS Out of bounds 
VECTOR_OVERFLOW Overflow 


pfnFunction Points to the address of the exception handler that receives con- 
trol when the specified exception occurs. If this parameter is zero, the DosSet- 

Vec function removes the current exception handler. For a full description, see 

the following “Comments” section. 


Return Value 


Comments 


Restrictions 


See Also 


Corrections 


DosShutdown 
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ppfnPrev Points to the variable that receives the address of the previous 
exception handler. The new exception handler can use this address to chain 
exception handling through all previous handlers or to restore the previous 
exception handler. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_FUNCTION 


When the system calls the exception handler, it enables interrupts and pushes 
the machine status word and far return address on the stack. If the exception 
handler returns, it must use the iret (return-from-interrupt) instruction. 


If the DosSetVec function is used to install an exception handler for the vector 
VECTOR_EXTENSION_ERROR, the function sets the machine status word to 
indicate that no 80287 processor is available. The emulation bit is set and the 
monitor-processor bit is cleared. (This is done without regard for the true state 
of the hardware.) If the DosSetVec function is used to remove the exception 
handler for VECTOR_EXTENSION_ERROR,, the function sets the machine 
status word to reflect the true state of the hardware. 


If the routine being registered is in a segment that has the iopl instruction indi- 
cated, the exception when it occurs, causes a general protection fault and the 
process is terminated. 


In real mode, the following restriction applies to the DosSetVec function: 


m@ Because the 8086 and 8088 microprocessors do not raise this exception, 
usVecNum cannot be VECTOR_EXTENSION_ERROR. 


DosDevConfig, DosError 


The exception handler must not be in an IOPL segment or the exception will 
cause a general protection fault. 


New 


USHORT DosShutdown ( u/Reserved) 


-ULONG u/Reserved; 


Parameters 


Return Value 


Comments 


/« must be zero »«/ 


The DosShutdown function flushes all system buffers and closes down the file 
system. After calling DosShutdown, no process can access the file system until 
the computer is rebooted. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_PARAMETER 


The DosShutdown function may take as much as several minutes to return, 
depending on the amount of data being written to the disk. 


Because it is not possible to swap memory to the disk once the DosShutdown 
function has been called, some functions may fail due to a lack of memory in 
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™@ DosStartSession 


low memory situations. All memory that the calling process may need should be 
allocated before calling DosShutdown; this includes implicit memory allocation 
that may be done by system functions for the calling process. 


Correction 


USHORT DosStartSession( pstdata, pidSession, ppid) 
PSTARTDATA pstdata; /« pointer to structure with session data —+/ 
PUSHORT pidSession; /» pointer to variable for session identifier »/ 


PUSHORT ppid; 


Parameters 


Return Value 


Comments 


/« pointer to variable for process Identifier »/ 


The DosStartSession function starts a session (screen group) and specifies which 
program to start in that session. This function creates an independent session or 
a child session, depending on the value of the Related field in the STARTDAT. 
structure. 


pstdata_ Points to the STARTDATA structure that contains data describing the 
session to start. The STARTDATA structure has the following form: 


typedef struct _STARTIDATA { 
USHORT Length; 
USHORT Related; 
USHORT FgBg; 
USHORT TraceOpt; 


PSZ PgmTitle; 
PSZ PgmName; 
PBYTE PgmInputs; 
PBYTE TermQ; 

PBYTE Environment; 


USHORT InheritOpt; 
USHORT SessionType; 
PSZ IconFile; 
ULONG PgmHandle; 
USHORT PgmControl; 
USHORT InitXPos; 
USHORT InitYPos; 
USHORT InitXSize; 
USHORT InitYSize; 
} STARTDATA; 


pidSession Points to the variable that receives the identifier of the child ses- 
sion. 


ppid Points to the variable that receives the process identifier of the child 
process. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. ; 


The MS OS/2 session manager writes a data element into the specified queue 
when the child session created by the DosStartSession function terminates. A 
parent session can be notified when a child session has terminated by using the 
DosReadQueue function. When the child session terminates, the request value 
returned by DosReadQueue is zero, and the data-element format consists of two 
unsigned values: the session identifier and the result code. 


Only the process that calls the DosStartSession function should call the Dos- 
ReadQueue function. Only this process can address the notification data ele- 
ment. After reading and processing the data element, the calling process must 
use the DosFreeSeg function to free the segment that contains the data element. 
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A child session is created when the Related field of the STARTDATA structure 
is set to TRUE. 


The process identifier of the child process cannot be used with MS OS/2 func- 
tions, such as DosSetPrty, that require a parent process/child process relation- 
ship. 


An independent session is created when the Related field of the STARTDATA 
structure is set to FALSE. An independent session is not under the control of 
the starting session. The DosStartSession function does not copy session and 
process identifiers for an independent session to the pidSession and ppid parame- 
ters. 


New sessions can be started in the foreground only when the caller’s session (or 
one of the caller’s descendant sessions) is currently executing in the foreground. 
The new session appears in the shell switch list. 


See Also DosCreateQueue, DosExecPgm, DosFreeSeg, DosReadQueue, DosSelect- 
Session, DosSetPrty, DosSetSession, DosStopSession 


Corrections The comments incorrectly stated that an independent session was created when 
the Related field of the STARTDATA structure is set to TRUE. The Related 
field must be set to FALSE to create an independent session. 


DosSubAlloc Correction 
USHORT DosSubAlloc( se/, pusOffset, cbBlock) 

SEL sel; /» segment selector »/ 

PUSHORT pusOffset; /» pointer to variable for offset »/ 

USHORT cbBlock; /« requested size of memory block »«/ 


The DosSubAlloc function allocates memory in a segment that was allocated 
previously by using the DosAllocSeg or DosAllocShrSeg function and that was 
initialized by using the DosSubSet function. 


The DosSubAlloc function is a family API function. 

Parameters sel Specifies the selector of the data segment in which the memory should be 
allocated. 
pusOffset Points to the variable that receives the offset to the allocated block. 
cbBlock Specifies the size (in bytes) of the requested memory block. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_NOMEM 


Comments The cbBlock parameter must not be greater than the maximum size of the seg- 
ment minus 8 bytes. Since all memory blocks are aligned on byte boundaries, the 
cbBlock parameter does not need to be a multiple of 16; however, it will be 
rounded to a multiple of 4. 


DosSubAlloc can be issued from ring 2 or ring 3; the suballocation segment can 
be either a ring-2 or a ring-3 segment. 
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See Also DosAllocSeg, DosAllocShrSeg, DosSubFree, DosSubSet 

Corrections The cbBlock parameter is rounded to a multiple of 4 before being processed. 
DosSubFree Correction 
USHORT DosSubFree( sel, offBlock, cbBlock) 

SEL sel; /« segment selector »/ 

USHORT offBlock; /« block offset »/ 


USHORT cbBliock; /x number of bytes in block to free «/ 


The DosSubFree function frees memory that was allocated previously by using 
the DosSubAlloc function. 


The DosSubFree function is a family API function. | 
Parameters sel Specifies the selector of the data segment from which the memory should 
be freed. 


offBlock Specifies the offset of the memory block to be freed. This offset 
must have been created previously by using the DosSubAlloc function. 


cbBlock — Specifies the size (in bytes) of the block to free. This parameter 
should by a multiple of 4. If it is not, it will be rounded prior to being used by 
this function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 
ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_OVERLAP | 
Comments DosSubFree can be issued from ring 2 or ring 3; and the suballocation segment 
can be either a ring-2 or a ring-3 segment. 
See Also DosAllocSeg, DosSubAlloc, DosSubSet 
Corrections The cbBlock parameter is rounded to a multiple of 4 before being processed. 
DosWaitNmPipe Correction 
USHORT DosWaitNmPipe( pszName, u/TimeOut) 
PSZ pszName; /» pointer to pipe name «/ 
ULONG ulTimeOut; /« time-out value »/ 


The DosWaitNmPipe function waits for a named pipe to become available. 


Parameters pszName Points to the pipe name. The name is in the form \pipe\name for a 
local pipe and \\server\pipe\name for a remote pipe. 


ulTimeOut Specifies the amount of time (in milliseconds) MS OS/2 should 
wait for the pipe to become available. A value of NPLINDEFINITE_WAIT 
causes an infinite wait. A value of NPLDEFAULT_WAIT causes the system to 
wait for the default time specified by the call to the Panne ay function 
call that created this named pipe. 


Return Value 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_INTERRUPT 
ERROR_SEM_TIMEOUT 


Comments The DosWaitNmPipe function should be used only when the DosOpen function 
returns the ERROR_PIPE_BUSY error value. 
If more than one process has requested a named pipe that has become available, 
MS OS/2 gives the pipe to the process that has been waiting the longest. 

See Also DosOpen 

Corrections A value of NP_LINDEFINITE_WAIT for the ulTimeOut parameter specifies an 
infinite wait; a value of NP_DEFAULT_WAIT for ulTimeOut uses the default 
time-out specified in the DosMakeNmPipe function. 

DosWrite Correction 

USHORT DosWrite ( hf, pvBuf, cbBuf, pcbBytesWritten ) 

HFILE hf; /« file handle »/ 

PVOID pvBuf; /» pointer to buffer «/ 

USHORT cbButf; /« number of bytes to write »/ 


PUSHORT pcbBytesWritten; /» pointer to variable receiving byte count «/ 


Parameters 


Return Value 


Comments 


The DosWrite function writes data from a buffer to a file, then copies the 
number of bytes written to a variable. 


The DosWrite function is a family API function. 


hf Identifies the file that receives the data. This handle must have been created 
by using the DosOpen function. 


pvBuf Points to the buffer that contains the data to write. 
cbBuf Specifies the number of bytes to write. 
pcbBytesWritten Points to the variable receiving the number of bytes written. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_LINVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NOT_DOS_DISK 
ERROR_WRITE_FAULT 


The DosWrite function begins to write at the current file-pointer position. The 
file-pointer position can be changed by using the DosChgFilePtr function. 


If the specified file has been opened using the write-through flag, the DosWrite 
function writes data to the disk before returning. Otherwise, the system collects 
the data in an internal file buffer and writes the data to the disk only when the 
buffer is full. 
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The DosWrite function may write fewer bytes to the file than the number 
specified in the cbBuf parameter if there is not enough space on the disk for all 
of the requested bytes. The cbBuf parameter can be zero without causing an 
error—that is, writing no bytes is acceptable. 


The efficiency with which DosWrite writes to a disk is improved when cbBuf is 
set to a multiple of the disk’s bytes-per-sector size. When cbBuf is set this way, 
DosWrite writes directly to the disk, without first copying the data to an internal 
file buffer. (DosQFSInfo retrieves the bytes-per-sector value for a disk.) 


DosWrite can be used to write bytes or messages to a pipe. Each write to a mes- 
Sage pipe writes a message whose size is the length of the write; Dos Write 
automatically encodes message lengths in the pipe, so applications need not 
encode this information in the buffer being written. 


Writes in blocking mode always write all requested bytes before returning. In 
nonblocking mode, writes return either with all bytes written or none written; 
the latter will occur in cases where DosWrite would have to block in order to 
complete the request—for example, if there is no room in the pipe buffer or if 
the buffer is currently being written to by another client). 


An attempt to write to a pipe whose other end has been closed will return the 
error ERROR_BROKEN_PIPE. 


Example This example creates the file abc and calls the DosWrite function to write the 
contents of the abBuf buffer to the file: 


BYTE abBuf [512]; 

HEILE hf; 

USHORT usAction, cbBytesWritten, usError; 

usError = DosOpen("abc", Ghf, &usAction, OL, FILE_NORMAL, 
FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, OL); 

if (tusError) 


DosWrite (hf, /* file handle a/ 
abBuf, /* buffer address a/ 
sizeof (abBuf), /* buffer size a/ 
&cbBytesWritten) ; /* address of bytes written */ 
See Also DosChgfFilePtr, DosOpen, DosQFSInfo, DosRead, DosWriteAsyne 
Corrections DosWrite can be used to write bytes or messages to a pipe. Relevant informa- 


tion about writing to a named pipe has been added. 


DosWriteAsync Correction 
USHORT DosWriteAsync( hf, hsemRam, pusErrCode, pvBuf, cbBuf, pcbBytesWritten) 

HFILE hf; . /s file handle ; x/ 

PULONG hsemRam; /« pointer to RAM semaphore »/ 

PUSHORT pusErrCode; / pointer to variable for error value »/ 

PVOID pvBuf; /» pointer to buffer containing data to write »/ 

USHORT cbBuf; ; /« number of bytes in buffer »/ 

PUSHORT pcbBytesWritten; /» pointer to variable for bytes written »/ 


The DosWriteAsync function writes one or more bytes of data to a specified file. 
The function writes the data asynchronously—that is, the function returns 
immediately, but continues to copy data to the specified file while the process 
continues with other tasks. 


Parameters 


Return Value 


Comments 
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hf Identifies the file that receives the data. This handle must have been created 
previously by using the DosOpen function. 


hsemRam Points to the RAM semaphore that indicates when the function has 
finished reading the data. 


pusErrCode Points to the variable that receives an error value. 

pvBuf Points to the buffer that contains the data to write. 

cbBuf Specifies the number of bytes to write. 

pcbBytesWritten Points to the variable receiving the number of bytes written. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_LINVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_DOS_DISK 
ERROR_WRITE_FAULT 


The DosWriteAsynce function starts writing at the current file-pointer position. 
The file-pointer position can be changed by using the DosChgFilePtr function. 


If the specified file has been opened using the write-through flag, the Dos- 
WriteAsynce function writes data to an internal file buffer and to the disk before 
returning. If the write-through flag has not been set, the system collects the data 
in an internal file buffer and writes the data to the disk only when the buffer is 
full. 


The DosWriteAsyne function may write fewer bytes to the file than the number 
specified in the cbBuf parameter if there is not enough space on the disk for all 
the requested bytes. The cbBuf parameter can be zero without causing an 
error—that is, writing no bytes is acceptable. 


When the DosWriteAsync function has written the data, it clears the RAM 
semaphore pointed to by the hsemRam parameter. If the process uses the sema- 
phore to determine when data is available, it must use the DosSemSet function 
to set the semaphore before calling DosWriteAsync. 


The efficiency with which the DosWriteAsync function writes to a disk is 
improved when the cbBuf parameter is set to a multiple of the disk’s bytes-per- 
sector size. When cbBuf is set this way, the function writes directly to.the disk, 
without first copying the data to an internal file buffer. (The DosQFSInfo func- 
tion retrieves the byters-per-sector value for a disk.) 


DosWriteAsync can be used to write bytes or messages to a pipe. Each write to 
a message pipe writes a message whose size is the length of the write; DosWri- 
teAsync automatically encodes message lengths in the pipe, so applications need 
not encode this information in the buffer being written. 


In blocking mode, write operations always write all requested bytes before 
returning. In nonblocking mode, write operations return either with all bytes 
written or none written; the latter occurs in cases where DosWriteAsync has to 
block in order to complete the request (for example, if there is no room in the 
pipe buffer or if the buffer is currently being written to by another process). 


When the function tries to write to a pipe whose other end has been closed, it 
returns the error ERROR_BROKEN_PIPE. 
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Example This example creates the file abc.ext, sets a RAM semaphore, and calls the 
DosWriteAsync function to write the contents of the buffer abBuf to a file. 
When any additional processing is finished, the example calls the DosSemWait 
function to wait until DosWriteAsync has finished writing to the file. 


ULONG hsemWrite = O; 

BYTE abBuf [1024]; 

HFILE hf; 

USHORT usAction, cbBytesWritten; 

USHORT usWriteAsyncError; 

DosOpen("“abc.ext", &hf, &usAction, OL, FILE_NORMAL, 
FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN _SHARE_DENYWRITE, OL); 


DosSemSet (&hsemWrite) ; /* sets semaphore */ 
DosWriteAsync (hf, /* file handle */ 
&hsemWrite, /* semaphore address */ 
&usWriteAsyncError, /* return-code address a/ 
abBuf, /* buffer address a/ 
sizeof (abBuf), /7* buffer size a/ 
&cbBytesWritten) ; /* address of bytes written */ 


: /* Other processing would go here. */ 


DosSemWait (&hsemWrite, -1L); /* waits for DosWriteAsync */ 
if (usWriteAsyncError) { 


. /* Error processing would go here. */ 


See Also DosChgFilePtr, DosOpen, DosQFSInfo, DosReadAsync, DosSemSet, 
DosSemWait, DosWrite 

Corrections Information about using DosWriteAsyne with named pipes has been added. 

DosWriteQueue Correction 

USHORT DosWriteQueue( hqueue, usRequest, cbBuf, pbBuf, usPriority) 

HQUEUE hqueue; ' /« target-queue handle »/ 

USHORT usRequest; _/« request/identification data , »/ 

USHORT cbBuf; /« number of bytes to write »/ 

PBYTE pbBuf; /« pointer to buffer with element to write »/ 

UCHAR usPriority; /« priority of element to write »/ 


The DosWriteQueue function writes an element to the specified queue. The 
position of the element in the queue is determined by the value specified in the 
fQueueOrder parameter of the DosCreateQueue function when the queue was 
created; if this parameter was set to 0x0002 (priority queue), the usPriority 
parameter of the DosWriteQueue function can be used to set the priority of the 
element. After the element is written, the process that owns the queue can read 
the element by using the DosPeekQueue or DosReadQueue function. 


Parameters hqueue Identifies the queue to be written to. This handle must have been 
created or opened by using the DosCreateQueue or DosOpenQueue function. 


usRequest Specifies a program-supplied event code. MS OS/2 does not use 
this field; it is reserved for the program’s use. The queue owner can retrieve this 
value by using the DosPeekQueue or DosReadQueue function. 


cbBuf Specifies the number of bytes to be copied from the buffer pointed to 
by the pbBuf parameter. 
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pbBuf Points to the buffer that contains the element to be written to the 
queue. 


usPriority Specifies the element priority. This parameter can be any value 
from 0 through 15; 15 is the highest priority. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_NO_MEMORY 


Comments The DosWriteQueue function returns an error value if the queue has been 
closed by the process that owns it. 


If the queue owner uses a RAM semaphore to notify it when elements are added 
to the queue, the semaphore must be shared. If the notifying semaphore is a sys- 
tem semaphore, the writing process must have opened the semaphore by using 
the DosOpenSem function. 


Example This example opens a queue called \queues\queuename. In order to write to the 
queue, the process allocates shared memory, gives the memory to the queue 
owner, copies data to the shared memory, and calls DosWriteQueue. The pro- 
cess then frees the shared memory. The queue owner must also free the shared 
memory before it becomes available to the system again. For more information, 
see DosReadQueue. 


PID pidOwner ; 
SEL sel, selRecipient; 


DosOpenQueue (&pidOwner, &hqueue, 

"\\queues\\queuename") ; /* opens queue */ 
DosAllocSeg(512, &sel, SEG _GIVEABLE) ; 7* allocates shared memory */ 
DosGiveSeg(sel, pidOwner, &selRecipient); /* gives it to queue owner */ 


. /* Copy the data to the shared memory segment. */ 


DosWr iteQueue (hqueue, /* queue handle a/ 
oO, /* request data */ 
11, /* length of data a/ 
MAKEP (selRecipient, 0), /* data buffer a/ 
O); /* element priority a/ 
DosFreeSeg (sel) ; /* frees shared memory segment */ 
See Also DosCreateQueue, DosOpenQueue, DosOpenSem, DosPeekQueue, DosRead- 
Queue 
Corrections The example worked only for interthread communication. It has been replaced 


with an example that works for interprocess communication. 


The description of the cbBuf parameter incorrectly stated that this parameter 
contained the number of bytes to be written to the buffer. It now correctly states 
that this is the number of bytes to be written from the buffer. 
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EM_QUERYREADONLY | New 


Parameters 
Return Value 


EM. ag ela ae 
mp1 = /* not used, must be zero */ 


mp2 = Or. /* not used, must be zero */ 


An application sends the i ca pai ce ae message to retrieve the 
read-only state of an entry field. 


This message does not use any parameters. 


The return value is TRUE if the read-only state is set; otherwise it is FALSE. 


See Also EM_SETREADONLY 

EM_SETINSERTMODE New 
EM_SETINSERTMODE 
mpl = iad ci a i /* insert-mode flag 7 
mp2 = OL; /* not used, must be zero */ 
An application sends the EM_SETINSERTMODE message to set or clear the 
system insert-mode state. 

Parameters fInsertMode Low word of mp1. Specifies whether to set or clear the insert 


Return Value 


mode. If this parameter is TRUE, insert mode is turned on; if it is FALSE, 
insert mode is turned off. 


The return value is TRUE if the previous insert mode was on or FALSE if the 
previous insert mode was off. 


Comments This message changes the SV_INSERTMODE system constant to reflect the 
_ current insert-mode state. It also sends an EN_INSERTMODETOGGLE 

notification message. 

See Also EN_INSERTMODETOGGLE 

EM_SETREADONLY New 
EM_SETREADONLY 
mpl = MPFROMSHORT (fReadOnly) ; /* read-only state */ 
mp2 = OL; /* not used, must be zero */ 
An application sends the EM_SETREADONLY message to set the read-only 
state of an entry field. 

Parameters fReadOnly Low word of mp1. Specifies whether to set or remove the read- 


Return Value 


Comments 


See Also 


only state of the entry field. A value of TRUE sets the state. 
The return value is TRUE if the read-only state is set; otherwise, it is FALSE. 


When the read-only state of an entry field is set, the user cannot change the text 
within the entry field. 


EM_QUERYREADONLY 
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@ EM_SETTEXTLIMIT Change 


Parameters 
Return Value 


Comments 


See Also 


Changes 


EN_CHANGE 


EM_SETTEXTLIMIT 
mpl = ha aepcaaea eae cchMax) ; /* max. number of bytes */ 
mp2 = OL 7* not used, must be zero */ 


An application sends an EM_SETTEXTLIMIT message to set the maximum 
number of bytes an entry-field control can contain. 


cchMax Low word of mp1. Specifies the maximum number of bytes an entry 
field can hold. 


The return value is TRUE if the operation is successful or FALSE if there is not 
enough memory to hold the requested number of characters. 


Sending an EM_SETTEXTLIMIT message causes memory to be allocated from 
the control heap for the specified maximum number of bytes. Failure to allocate 
sufficient memory results in a WM_CONTROL message, with the ~ 
EN_MEMERROR notification code being sent to the owner window. 


WM..CONTROL 


All references to characters have been replaced by bytes to accommodate sys- 
tems in which a character may be composed of more than one byte. 


| New 


Parameters 


Return Value 
See Also 


"WM_CONTROL 


id = (USHORT) SHORTIFROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = EN_CHANGE; 
hwndEdit = HWNDEROMMP (mp2) ; /* window handle of entry field */ 


The EN_CHANGE notification message is sent when the text in an entry field 
changes. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to EN.CHANGE. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


An application should return zero if it processes this message. 


WM_CONTROL 


EN_INSERTMODETOGGLE New 


WM_CONTROL 

id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID a/ 
usNotifyCode = EN_INSERTMODETOGGLE ; 
hwndEdit = HWNDEROMMP (mp2) ; /* window handle of entry field */ 


The EN_INSERTMODETOGGLE notification message is sent when the insert 
mode of an entry-field control is toggled. 
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Parameters 


Return Value 
See Also 


EN_KILLFOCUS 


Parameters 


See Also 


id Low word of mp1 . Identifies the control window. 
usNotifyCode High word of mp1. Set to EN_.INSERTMODETOGGLE. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


An application should return zero if it processes this message. 


EM_SETINSERTMODE, WM_CONTROL 


New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID s/ 
usNotifyCode = EN_KILLFOCUS; 
hwndEdit = HWNDEROMMP (mp2) ; /* window handle of entry field */ 


The EN_KILLFOCUS notification message is sent when an entry-field con) 
loses the input focus. 


_ id Low word of mp1. Identifies the control window. 


usNotifyCode High word of mp1. Set to EN_KILLFOCUS. 


hwndEdit Low and high word of mp2. Identifies the entry-field window. 


EN_SETFOCUS, WM_CONTROL 


EN_.MEMERROR New 


Parameters 


See Also 


EN_OVERFLOW 


WM_CONTROL ; 

id = (USHORT) SUN MENERROR Te /* control-window ID */ 
usNotifyCode = EN_MEMERRO 

hwndEdit = HWNDEROMMP (mp2) : /* window handle of entry field */ 


The EN_MEMERROR notification message is sent when an entry-field control 
cannot allocate the memory necessary to accommodate window text of the length 
specified by the EM_SETTEXTLIMIT message. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to EN.MEMERROR. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


EM_SETTEXTLIMIT, WM_CONTROL 


New 
WM_CONTROL 
id = (USHORT) SHORTIFROMMP (mp1) ; /* control-window ID */ 
usNotifyCode = EN_OVERFLOW 
hwndEdit = HWNDFROMMP (mp2) ; /* window handle of entry field */ 


The EN_OVERFLOW notification message is sent when the text limit in an 
entry field is exceeded. 


Parameters 


Return Value 
See Also 


EN_SCROLL 


Parameters 


Return Value 
See Also 
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id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to ENLOVERFLOW. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


An application should return TRUE to retry the operation. 


WM_CONTROL 
New 
EN_SCROLL 
. dd = (USHORT) SHORT1FROMMP (mp2) ; /* control-window ID a/ 
usNotifyCode = EN_SCROLL; ; 
hwndEdit = HWNDEROMMP (mp2) ; /* window handle of entry field */ 


The EN_SCROLL notification message is sent to the owner of the entry-field 
window when a scroll-bar event occurs. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to EN_SCROLL. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


An application should return zero if it processes this message. 


WM_CONTROL 


EN_SETFOCUS New 
WM_CONTROL 
_id = (USHORT) SHORTLFROMMP (mp2) ; /* control-window ID a/ 
usNotifyCode = EN_SETFOCUS; 
hwndEdit = HWNDFROMMP (mp2) ; /* window handle of entry field */ 


Parameters 


See Also 


The EN_.SETFOCUS notification message notifies an application when an entry 
field receives the input focus. 


id Low word of mp1. Identifies the control window. 
usNotifyCode High word of mp1. Set to EN_SETFOCUS. 
hwndEdit Low and high word of mp2. Identifies the entry-field window. 


EN_KILLFOCUS, WM_CONTROL 
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HE GpiCallSegmentMatrix Correction 
LONG GpiCallSegmentMatrix( hps, idSegment, cElements, pmatif, IType) 
HPS hps; /»« presentation-space handle »/ 
LONG idSegment; /» segment identifier »/ 
LONG cElements; /« number of matrix elements to examine »/ 
PMATRIXLF pmatif; /» address of structure for matrix «/ 
LONG /Type; /» transformation modifier «/ 


The GpiCallSegmentMatrix function draws the specified segment using an 
instance transformation. The function combines the instance transformation 
pointed to by pmatlf with the current model transformation, then draws the seg- 
ment as if calling the GpiDrawSegment function. The combined transformation 
applies only while the function draws the segment. GpiCallSegmentMatrix does 
not modify the current model transformation. 


Parameters hps Identifies the presentation space. 


idSegment Specifies the segment to draw. This value must be greater than 
zero. 


cElements Specifies the number of matrix elements pointed to by pmailf. It 
can be any value from 0 through 9. 


pmatlf Points toa MATRIXLF structure that contains the matrix for the 
instance transformation. Although a transformation requires nine matrix ele- 
ments, the function copies from the structure only the number of matrix ele- 
ments specified by cElements. If cElements is less than nine, the function sup- 
plies the remaining elements by substituting corresponding elements from the 
identity matrix. 


_ The MATRIXLF structure has the following form: 


typedef struct _MATRIXLF { 
FIXED f£xM11; 
FIXED f£xM12; 
LONG 1M13; 
FIXED fxM21; 
FIXED f£xM22; 


LONG 1M23; 

LONG 1M31; 

LONG 1M32; 

LONG 1M33; 
} MATRIXLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


IType Specifies how to combine the instance transformation with the model 
transformation. It can be one of the following values: 


Value Meaning 

TRANSFORM_ADD Adds the model transformation to the 
instance transformation (MODEL * 
INSTANCE). 

TRANSFORM_PREEMPT Adds the instance transformation to the 

model transformation (INSTANCE * * 

MODEL). 

TRANSFORM_REPLACE Replaces the model transform with the 


instance transformation. 


Return Value 


Errors 


Example 


See Also 


Corrections 
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The return value is GPILOK or GPI_HITS if the function is successful (it is 
GPLHITS if the detectable attribute is set for the presentation space and a 
correlation hit occurs). The return value is GPILERROR if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_CALLED_SEG_IS_CURRENT 
PMERR_CALLED_SEG_NOT_FOUND 
PMERR_INV_HPS 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_MATRIX_ELEMENT 
PMERR_INV_MICROPS_FUNCTION 
PMERR_INV_SEG_NAME ) 
PMERR_INV_TRANSFORM_TYPE 
PMERR_PS_BUSY 
PMERR_SEG_CALL_RECURSIVE 
PMERR_SEG_NOT_FOUND 


This example calls the GpiCallSegmentMatrix function to draw a segment three 
times. Each time the segment is drawn, the instance transformation doubles in 
size. The result is three triangles with the last triangle twice the size of the 
second, and the second twice the size of the first. 


POINTL ptiStart = { 0, O }; 
POINTL ptilTriangle[{] = { 100, 100, 200, 0, O, O }; 
MATRIXLF matlfInstance = { MAKEFIXED(1, 0), MAKEFIXED(O, 0), O, 
MAKEFIXED(O, 0), MAKEFIXED(1, 0), O, 
1 


O, O, I; 
GpiOpenSegment(hps, 1L); /* opens segment */ 
GpiMove(hps, &ptlStart); /* moves to start point (0, 0) */ 
GpiPolyLine(hps, 3L, ptlTriangle) ; /* draws triangle */ 
GpiCloseSegment (hps) ; /* closes segment */ 


for (i = O; i < 3; i++) 


x 


* Draw the segment after adding the matrix to the model 
* transformation. 
k 


GpiCallSegmentMatrix(hps, 1L, 9, &matlfInstance, TRANSFORM_ADD) ; 
matlfInstance.fxM1l *= 2; : 
matlfInstance.f£xM22 *= 2; 


GpiDrawSegment 


In the example, the MAKEFIXED macro is required to create FIXED values for 
initializing the structure. 
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HM GpiCreateLogFont Correction 
LONG GpiCreateLogFont( hps, pchName, Icid, pfat) 
HPS hps; /« presentation-space handle »/ 
PSTR8 pchName; /»« address of logical-font name s/ 
LONG Icid; /« localidentifier —. s/ 
PFATTRS pfat; /»« address of structure for font attributes «/ 


The GpiCreateLogFont function creates a logical font. A logical font is a list of 
font attributes, such as face name, average width, and maximum height, that an 
application uses to request a physical font. A physical font is the bitmap or vec- 
tor information the system uses to draw characters on a device. Applications 
create logical fonts to specify the fonts they need, and the system maps the logi- 
cal fonts to matching physical fonts. 


GpiCreateLogFont creates a logical font using the font attributes specified in the 
structure pointed to by the pfat parameter. Each logical font has a local identifier 
and logical font name, specified by the /cid and pchName parameters, to 
uniquely identify it. The local identifier can then be used in subsequent graphics 
functions to identify the font. 


Since a physical font that exactly matches the logical font may not be available, 
the system usually maps the logical font to the closest matching physical font. — 
The system uses rules to map the font—for example, it chooses a font with a 
greater height if a font of the exact height is not available. An application can 
force the system to choose a particular font by setting the value of the IMatch 
field in the FATTRS structure to be that returned for the desired font by the 
GpiQueryFonts function. After GpiCreateLogFont chooses the physical font, 
this choice does not change for a particular logical font. 


Parameters hps Identifies the presentation space. 


pchName Points to an 8-character logical-font name. It can be NULL, if no 
logical font name is desired. 


Icid Specifies the local identifier that the application uses to refer to this font. 
It must be in the range 1 through 254. It is an error if this parameter is already 
in use to refer to a font or bitmap. 


pfat Points to a FATTRS structure that will contain the attributes of the logical 
font that is created. The FATTRS structure has the following form: 


typedef struct _FATTRS { 
USHORT usRecordLength; 
USHORT fsSelection; 
LONG 1Match; 
CHAR szFaceName [FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG lMaxBaselineExt; 
LONG lAveCharWidth; 
USHORT fsType; . 
SHORT sQuality; 
USHORT fsFontUse; 

} FATTRS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is FONT_MATCH if a matching font is found, 
FONT_DEFAULT if a matching font could not be found, or zero if an error 
occurred. 


Errors 


Comments 


Example 


See Also 


Corrections 
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Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_FONT_NOT_LOADED 
PMERR_INV_FONT_ATTRS 
PMERR_INV_HPS 

PMERR_INV_SETID 
PMERR_KERNING_NOT_SUPPORTED 
PMERR_PS_BUSY 
PMERR_SETID_IN_USE 


To choose the system default font, set the face name to NULL and all other 
attributes in the FATTRS structure, except the code page, to zero. 


To use'a font, the application sets the font for the presentation space by specify- 
ing the local identifier for the corresponding logical font with the GpiSetCharSet 
function. Once a font is set, the system uses the font for subsequent text output. 


This example uses the GpiCreateLogFont function to create a logical font with 
the local identifier 1. The logical font has the face name “Courier” and requested 
width and height of 12 pels. Once the font is created, the example sets the font 
using the local identifier and displays a string in the font at the point (100,100). 


USHORT i; 

POINTL ptl = { 100, 100 }; 

FATTRS fat; 

fat.usRecordLength = sizeof(FATIRS); /* sets size of structure / 
fat. fsSelection = 0; /* uses default selection a/ 
fat.1Match = OL; /* does not force match */ 
fat.idRegistry = 0; /* uses default registry a/ 
fat.usCodePage = 850; /* code-page 850 */ 
fat.1MaxBaselineExt = 12L; /* requested font height is 12 pels */ 
fat.lAveCharWidth = 12L; /* requested font width is 12 pels */ 
fat.fsType = 0; /7* uses default type / 


fat.fsFontUse = FATTR_FONTUSE_NOMIX; /* does not mix with graphics */ 


/* Copy Courier to szFacename field. */ 


for (i=0; fat.szFacename[i] = "Courier"[i]; i++); 

GpiCreateLogFont (hps, /* presentation space a/ 
NULL, /* does not use logical font name a/ 
1L, /* local identifier * 
&fat); /* structure with font attributes a/ 

GpiSetCharSet(hps, 1L); /* sets font for presentation space */ 

GpiCharStringAt (hps, &ptl, 5L, "“Hello"); /* displays a string */ 


GpiCharStringAt, GpiCreateLogFont, GpiQueryFonts, GpiSetCharSet 


In the example, the fat.fsType field should be set to 0 rather than to 
FATTR_TYPE_FIXED. 
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—E GpiDestroyPS 


Correction 


BOOL GpiDestroyPS(hps) 
HPS hps; /« presentation-space handle «/ 


. 


Parameters 
Return Value 


Errors 


Example 


See Also 


Corrections 


HZ GpiGetData 


HPS hps; 
LONG idSegment; 
PLONG poff; 


LONG cmdFormat; 


LONG cb; 


The GpiDestroyPS function destroys the presentation space and releases all 
resources owned by the presentation space. This function should only be used to 
destroy presentation spaces created by the GpiCreatePS function. 


hps Identifies the presentation space. 


The return value is GPLOK if the function is successful or GPILERROR if an 
error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HPS 
PMERR_PS_BUSY 
PMERR_PS_IS_ASSOCIATED 


This example uses the GpiDestroyPS function to destroy the presentation space 
associated with a memory device context: 

HDC hdc; 

HPS hps; 

SIZEL page = { O, O }; 

/* Create the memory device context and presentation space. */ 


hdc = DevOpenDC (hab, OD_MEMORY, "*", OL, NULL, NULL); 
hps = GpiCreatePS (hab, hdc, &page, PU_ PELS | GPIT_ MICRO | GPIA_ASSOC) ; 


GpiAssociate(hps, NULL) ; 


GpiDestroyPS (hps) ; i destroys presentation space my 
DevCloseDC (hdc) ; /* closes device context a/ 
GpiCreatePS 


In the example, GpiAssociate must be called before DevCloseDC. This is true 
whenever a device context is associated with a presentation space. 


Correction 

LONG GpiGetData(hps, idSegment, poff, cmdFormat, cb, pb) 
; /« presentation-space handle af 

/«x segment identifier s/ 

/« address of variable for segment offset »/ 

/« conversion type »/ 

/« length in bytes of the data buffer «/ 

/« address of buffer for data »/ 


PBYTE pb; 


The GpiGetData function copies graphics orders from the specified segment to 
the specified buffer. The function continues to copy the graphics orders from the 
segment to the buffer until all orders in the segment have been copied or the 
number of bytes specified by the cb parameter have been copied. If the function 


Parameters 


Return Value 


Errors 
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fills the buffer, the last order in the buffer may not be complete since the func- 
tion does not stop on an order boundary when copying to the buffer. In any 
case, the function returns the number of bytes copied to the buffer. 


The function starts copying graphics-order data from the location specified by 
the poff parameter. If this parameter is zero, the function copies from the begin- 
ning of the segment. After copying the data, the function replaces the value in 
poff with the offset to the next byte of data to copy from the segment (if any). 
This value can be used to specify the next location to copy. 


The GpiGetData function cannot be used to copy data from an open segment, 
but it can be used to copy data while some other segment is open. 

hps Identifies the presentation space. 

idSegment Specifies the segment identifier. 


poff Points to the variable that contains the offset from the beginning of the 
segment to the next byte of graphics order data to copy. If this parameter is 
zero, the function copies from the beginning of the segment. 


cmdFormat Specifies the coordinate conversion type. It can be one of the 
following values: 


Value Meaning 

DFORM_NOCONV Copies coordinates without converting. The coordi- 
nates are in the format used by the presentation 
space. 

DFORM_PCLONG ' Converts coordinates to PC-format long (4-byte) 
integers. 

DFORM_PCSHORT Converts coordinates to PC-format short (2-byte) 
integers. 

DFORM_S370SHORT Converts coordinates to S/370-format short (2-byte) 
integers. 


cb_ Specifies the length in bytes of the buffer to receive the graphics orders. 
pb Points to the buffer that receives the graphics-order data. 


The return value is the number of graphics-order bytes copied if the function is 
successful or GPILALTERROR if an error occurred. 


‘Use the WinGetLastError function to retrieve the error value, which may be one 


of the following: 


PMERR_DATA_TOO_LONG 
PMERR_INV_GETDATA_CONTROL 
PMERR_INV_HPS 
PMERR_INV_LENGTH 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_MICROPS_FUNCTION 
PMERR_INV_SEG_NAME 
PMERR_INV_SEG_OFFSET 
PMERR_PS_BUSY 
PMERR_SEG_IS_CURRENT 
PMERR_SEG_NOT_FOUND 
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Example 


See Also 
Corrections 


GpiLoadFonts 


This example uses the GpiGetData function to copy data from one segment to 
another: 


LONG fFormat = DFORM_NOCONV; /* does not convert coordinates a/ 


LONG offSegment = OL; /* offset in segment a/ 
LONG offNextElement = OL; /* offset in segment to next element */ 
LONG cb = OL; /* bytes retrieved * 
BYTE abBuf fer [512]; 

GpiOpenSegment (hps, 3L); /* opens segment to receive data a / 
do { 


offSegment += cb; 
offNextElement = offSegment; 
cb = GpiGetData(hps, 2L, &offNextElement, fFormat, 512L, abBuffer) ; 


7* put data in other segment */ 


if (cb > OL) GpiPutData(hps, /* presentation-space handle a/ 
fFormat, /* format of coordinates a/ 
&cb, /* number of bytes in buffer &/, 
abBuffer); /* buffer with graphics-order data */ 

} while (cb > O); 


GpiCloseSegment (hps) ; /* closes segment that received data */ 


GpiPutData 


The poff parameter is a pointer to the variable that contains the offset; the 
cmdFormat parameter is an integer that specifies the conversion format. 


Correction 


BOOL GpiLoadFonts( hab,.pszFileName) 


HAB hab; 
PSZ pszFileName; 


Parameters 


Return Value 


Error 


/« anchor-block handle «/ 
/« pointer to filename — «/ 


The GpiLoadFonts function loads fonts from the specified resource file. Once 
loaded, the fonts are private fonts and can be used by any thread in the process. 
Any other process can use the fonts but only if it also loads the font by using the 
GpiLoadFonts. The function loads a copy of the fonts once only. Any subse- 
quent call to the function by another process for the same fonts simply incre- 
ments the use count for the resource and gives that process access. 


hab Identifies the anchor block. 


pszFileName Points to a null-terminated string. This string must be a valid 
MS OS/2 filename. If it does not specify a path and the filename extension, the 
function appends the default extension (.d/l) and searches for the font resource 
file in the directories specified by the libpath command in the config.sys file. 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be the 
following: 


PMERR_INV_FONT_FILE_DATA 


Example 


See Also 


Corrections 


GpiOutlinePath 
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This example uses the GpiLoadFonts function to load all fonts from the font 
resource file helv.dll. The GpiQueryFonts function retrieves the number of fonts 
loaded. 


LONG cEFonts = OL; 


GpiLoadFonts (hab, "helv"); 
cFonts = GpiQueryFonts (hps, QF_PRIVATE, NULL, &cFonts, OL, NULL); 


GpiCreateLogFont, GpiDeleteSetId, GpiQueryFonts, GpiUnloadFonts 


In the example, the function loads fonts from the helv.dil file, not the helv.fon 
file. If no path and filename extension are given, the function by default searches 
for a file that has the .d/l extension. — 


New 


LONG GpiOutlinePath( hps, /Path, /Options) 


HPS hps; 
LONG /Path; 
LONG /Options; 


Parameters 


Return Value 


Errors 


Comments 


See Also 


/« presentation-space handle _ »/ 
/» identifies path to be outlined «/ 
/« reserved, must be zero »/ 


The GpiOutlinePath function draws an outline of a path using the current line 
attributes. This function draws the outline such that each line, curve, and other 
item in the path appears to be drawn individually; it does not close the path. 
GpiOutlinePath draws the path using the current cosmetic line width (see the 
GpiSetLineWidth function); it does not fill the path. GpiOutlinePath deletes the 
path after drawing the outline. 


hps Identifies the presentation space. 


IPath Identifies the path to be outlined. For MS OS/2, version 1.2, this 
parameter must be set to 1. 


IOptions Specifies outline options. For MS OS/2, version 1.2, this parameter 
must be set to zero. 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HPS 
PMERR_INV_PATH_ID 
PMERR_INV_RESERVED_FIELD 
PMERR_PATH_UNKNOWN 
PMERR_PS_BUSY 


If character strings are in the path, the function draws the outline of each char- 
acter but does not fill the interior of the character, giving the appearance of hol- 
low characters. For small characters, outlining in this way can give a visual 
appearance similar to filled characters, but with improved performance. 


GpiBeginPath, GpiEndPath, GpiSetLineWidth 
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H GpiPlayMetaFile Correction 
LONG GpiPlayMetaFile ( hps, hmf, cOptions, alOptions, pcSegments, cchDesc, pszDesc) 
HPS hps; /« presentation-space handle »/ 
HMF hrf; /»« metafile handle »/ 
LONG cOptions; /« number of elements in array »/ 
PLONG al/Options; /»« address of array of load options x/ 


PLONG pcSegments; /» address of count of renumbered segments +/ 


LONG cchDesc; 
PSZ pszDesc; 


Parameters 


Return Value 


Errors 


/« number of bytes in record »/ 
/« address of buffer for descriptive record »/ 


The GpiPlayMetaFile function plays the metafile specified by the hmf parameter. 
The function plays the metafile file by converting the graphics data in the file to 
graphics operations for the given presentation space. The function uses the load 
options specified by the alOptions parameter to determine how to prepare the 
presentation space for playing the metafile. This may include resetting the 
presentation space, replacing tagged bitmaps and logical fonts, and replacing the 
logical color table. 


Since the metafile may create segments, the application must close any open seg- 
ment before calling GpiPlayMetaFile. If the metafile creates segments, the func- 
tion retains the segments only if the current drawing mode is DM_RETAIN or 
DM_DRAWANDRETAIN. If chained segments are retained, the function adds 
them to the end of the existing segment chain. 


The GpiPlayMetaFile function can play a metafile any number of times. 


hps Identifies a presentation space. 


hmf Identifies the metafile to play. It must have been created or loaded previ- 
ously by using the DevOpenDC or GpiLoadMetaFile function. 


cOptions Specifies the number of elements in the array pointed to by the 
alOptions parameter. 


alOptions Points to the array specifying the load options. For a full descrip- 
tion, see the following “Comments” section. 


pceSegments Points to a variable for the count of renumbered acementy: This 
parameter is reserved and is set to zero. 


cchDesc Specifies the number of bytes in the buffer pointed to by the pszDesc 
parameter. 


pszDesc_ Points to the buffer that receives the null-terminated string describing 
the metafile. This descriptive record is the record set by the DevOpenDC func- 
tion for the metafile. If the buffer is smaller than the record, the function trun- 
cates the record. 


The return value is GPILOK or GPLHITS if the function is successful (it is 
GPLHITS if the detectable attribute is set for the presentation space and a 
correlation hit occurs). The return value is GPILERROR if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following values: 


PMERR_INCOMPATIBLE_METAFILE 
PMERR_INV_ELEMENT_POINTER 
PMERR_INV_HMF 

PMERR_INV_HPS 


Comments 
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PMERR_INV_IN_CURRENT_EDIT_MODE 
PMERR_LINV_LENGTH 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_METAFILE 
PMERR_INV_MICROPS_ORDER 
PMERR_INV_OUTSIDE_DRAW_MODE 
PMERR_INV_PLA Y_METAFILE_OPTION 
PMERR_PROLOG_ERROR 
PMERR_PS_BUSY _. 
PMERR_STOP_DRAW_OCCURRED 


The GpiPlayMetaFile function uses several options to control how a metafile is 
played. The options are specified in an array passed to the function by using the 
alOptions parameter. The array has at most ten elements, and there are eight 
predefined array indexes that can be used to access these elements. The follow- 
ing list describes the purpose and possible values for each element: 


- PMF_SEGBASE Specifies a reserved element. It must be zero. 


PMF_LOADTYPE Specifies the transformation to use when playing the 
metafile. It can be one of the following values: 


Value Meaning 
LT_DEFAULT Default; same as LT_NOMODIFY. 
LT_NOMODIFY Use the current viewing transformation as set by the 


application by using the GpiSetViewingTransform- 
Matrix function. This is the default action. 


LT_LORIGINALVIEW _ Use the viewing transformations defined in the 
metafile. 


PMF_RESOLVE Specifies a reserved element. It must be RS_DEFAULT or 
RS_NODISCARD. 


PMF_LCIDS Specifies whether to use tagged bitmaps and logical fonts from 
the metafile or from the application. It can be one of the following values: 
metafile or from the application. It can be one of the following values: 


Value Meaning 
LC_DEFAULT Default; same as LC_NOLOAD. 
LC_NOLOAD Use the tagged bitmaps and logical fonts defined by 


the application. The application must define the 
appropriate objects and local identifiers before playing 
the metafile. This is the default. 


LC_LOADDISC Use the tagged bitmaps and logical fonts defined in 
the metafile. The function loads the object from the 
metafile and assigns a local identifier. If the local 
identifier is already defined by the application, the 
function deletes the identifier before creating the new 
object. 
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PMF_RESET Specifies whether the presentation space should be reset before 
playing the metafile, with the page units and size being set as defined in the 
metafile. It can be one of the following values: 


Value 


RES_DEFAULT 


Meaning 


Default; same as RES_NORESET. 


RES_NORESET 
RES_RESET 


Does not reset the presentation space. 


Resets the presentation space. The function resets the 
page units and page size to the values specified by the 
metafile. It then sets up default transformations, 
based on page units and size, as if the presentation 
space had just been created with these values, and 
modifies the device transformation (if necessary) to 
ensure that the physical size of the metafile picture is 
preserved. Finally, it resets the presentation space as 
if calling the GpiResetPS function with the 
GRES_ALL option. 


PMF_SUPPRESS Specifies whether to continue playing the metafile after reset- 
ting the presentation space. It can be one of the following values: 


Value 


SUP_DEFAULT 
SUP_NOSUPPRESS 
SUP_SUPPRESS 


Meaning 


Default; same as SUP_NOSUPPRESS. 
Does not suppress the metafile. 


Suppresses the metafile after the presentation space is 
reset as specified by the PMF_RESET option. All 
other options are ignored. 


PMF_COLORTABLES Specifies whether to use logical color tables from the 
metafile or from the application. It can be one of the following values: 


Value 


CTAB_DEFAULT 
CTAB_NOMODIFY 


CTAB_REPLACE 


Meaning 


Default; same as CTABLNOMODIFY. 


Uses the logical color table defined by the application. 
This is the default. 


Uses the logical color tables implied by or given in the 
metafile. The application’s existing logical color table 
is overwritten. 


PMF_COLORREALIZABLE Specifies whether the logical color tables 
defined by the metafile should be realizable. It can be one of the following 


values: 
Value 


Meaning 


CREA_DEFAULT 
CREA_REALIZE 
CREA_NOREALIZE 


Default; same as CREA_NOREALIZE. 
Creates realizable color tables. 


Does not create realizable color tables. This is the 
default. 
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PMF_PATHBASE Specifies a reserved element. It must be zero. 


PMF_RESOLVEPATH Specifies a reserved element. It must be 
RSP_DEFAULT or RSP_NODISCARD. 


Example This example uses the GpiPlayMetafFile function to play the given metafile. The 
function uses all the default actions for playing the metafile. 
HMF hmf; 


LONG cSegments; 
CHAR szBuffer [80]; 


hmf = GpiLoadMetafile(hab, "sample.met") ; 
GpiPlayMetafile(hps, hmf, OL, NULL, &cSegments, 80L, szBuffer) ; 


See Also DeyvCloseDC, DevOpenDC, GpiCreateLogColorTable, GpiCreateLogF ont, 
GpiLoadMetaFile, GpiResetPS, GpiSetDrawingMode, GpiSetViewing- 
TransformMatrix 


Corrections The default value for PMF_COLORREALIZABLE is CREA_NOREALIZE, 
not CREA_REALIZE. 


GpiPolyLine Correction 
LONG GpiPolyLine(hps, cptl, apt/) 

HPS hps; /»« presentation-space handle »/ 

LONG cpii; /« number of points in array »/ 


PPOINTL apt; /« address of array of structures for points «/ 


The GpiPolyLine function draws one or more straight lines. The function draws . 
the lines by using the points specified by the aptl parameter. The function needs 
at least one point to draw a line. If a point is specified, the function draws the 
line from the current position to the point. For each additional line, the function 
needs exactly one more point, and uses the end point of the last line as the start- 
ing point for the next. The function draws the lines by using the current values 

of the line-color, line-mix, line-width, and line-type attributes. 


The GpiPolyLine function moves the current position to the end point of the last 
line. 


Parameters hps Identifies a presentation space. 


cptl Specifies the number of points. This parameter must be greater than or 
equal to zero. 


aptl Points to an array of POINTL structures that contains the points. The 
POINTL structure has the following form: 


typedef struct _POINTL { 
LONG x; 

LONG 
} POINTL; 


Return Value The return value is GPILOK or GPLHITS if the function is successful (it is 
GPLHITS if the detectable attribute is set for the presentation space and a 
correlation hit occurs). The return value is GPILERROR if an error occurs. 
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PBYTE pbBuffer; 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 
PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_PS_BUSY 
Example This example uses the GpiPolyLine function to draw a triangle: 
POINTL ptlTriangle[{] = { 100, 100, 200, 0, O, O }; 
GpiMove(hps, &ptlTriangle[2]); /* moves to end point (0, 0) */ 
GpiPolyLine(hps, 3L, &ptlTriangle[1]); /* draws.triangle a/ 
See Also GpiLine, GpiMove, GpiSetAttrs, GpiSetColor, GpiSetCurrentPosition, 
GpiSetLineType 
Corrections The example did not draw a triangle because the starting point for GpiPolyLine 
was the same point as that moved to in the GpiMove function. The GpiPolyLine 
function was also missing a parameter. 
GpiQueryBitmapBits Correction 
LONG GpiQueryBitmapBits(hps, /ScanStart, cScan, pbBuffer, pbmi) . 
HPS hps; /» presentation-space handle »/ 
LONG /ScanStart; /« number for first scan line to retrieve «/ 
LONG cScan; /»« number of scan lines to retrieve »/ 


/» address of buffer for bitmap image data «/ 


PBITMAPINFO pbmi; /»« address of structure for bitmap info »/ 


The GpiQueryBitmapBits function copies image data from a bitmap to the 
buffer pointed to by the pbBuffer parameter. The function copies the image data 
from the bitmap currently set for the presentation space. The presentation space 
must be associated with a memory device context. 


To copy the image data, the function needs the count of planes and adjacent 
color bits specified in the fields of the structure pointed to by the pbmi parame- 
ter. That is, the cPlanes and cBitCount fields must be set before you call the 
function. Also, the cbFix field must be set to 12. The function then copies the 
image data to the buffer. The buffer must have sufficient space to hold all the 
bytes of image data being copied. The number of bytes for the buffer is equal to 
the number of scan lines to copy, multiplied by the width of the bitmap in bytes 
(rounded up to the next multiple of 4), multiplied by the number of color planes. 
The width has to be a multiple of 4, since the function rounds the length of each 
scan line to a multiple of 4 bytes before copying. Also, the width must be multi- 
plied by the number of adjacent color bits before rounding. 


After copying the image data, the GpiQueryBitmapBits function fills the remain- 
ing fields in the structure pointed to by pbmi. These fields are the width and 
height of the bitmap and the array of RGB color values for the bitmap pels. An 
application must make sure there is sufficient space in the structure to receive all 
elements of the array of RGB color values. The number of elements in the array 
depends on the format of the bitmap. 


Parameters 


Return Value 


Errors 


Comments 
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hps Identifies the presentation space. 


IScanStart Specifies the number of the first scan line to copy to the buffer. If 
this parameter is zero, the function copies the first scan line in the bitmap. 


cScan Specifies the number of scan lines to copy. 


pbBuffer Points to the buffer that receives the bitmap image data. It must be 
large enough to hold all the bytes of the image data, from the scan line specified 
by the /ScanStart parameter to the end of the bitmap. 


pbmi_ Points to the BITMAPINFO structure that receives the bitmap informa- 
tion table. The BITMAPINFO structure has the following form: 


typedef struct _BITMAPINFO { 
ULONG cbF1ix; 
USHORT cx; 
USHORT cy; 
USHORT cPlanes; 
USHORT cBitCount; 
RGB argbColor [1]; 
} BITMAPINEFO; 


Depending on the format of the given bitmap, an application may need to allo- 
cate extra bytes for the structure to hold the additional elements for the 
argbColor field. 


The return value is the number of scan lines retrieved if the function i is success- 
ful or BMB_ERROR if an error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INCORRECT_DC_TYPE 
PMERR_INV_DC_TYPE 
PMERR_INV_HPS 
PMERR_INV_INFO_TABLE 
PMERR_INV_LENGTH_OR_COUNT 
PMERR_INV_SCAN_START 
PMERR_NO_BITMAP_SELECTED 
PMERR_PS_BUSY 


If the requested color format is not the same as the bitmap’s color format, the 
function converts the bitmap image data to the requested format. 


For any scan line, the bits for the pixels are tightly packed, with the bits for the 
first pixel stored in the most significant bits of the first byte. If necessary, a scan 
line is padded at the end so that each scan line begins on a 32-bit boundary. 
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Example 


See Also 
Corrections 


This example uses GpiQueryBitmapBits to copy the image data of a bitmap 
from a presentation space associated with a memory device context. 


BITMAPINEOHEADER bmp = { 12, 640, 350, 1, 1 }; 
LONG cbBuffer, chBitmapInfo; 

SEL selBuffer, selBitmapInfo; 

PBYTE pbBuffer; 

PBITMAPINFO pbmi; 


t 


* Compute the size of the image-data buffer and the bitmap 
* information structure. 


7, 


cbBuffer = (((bmp.cBitCount * bmp.cx) + 31) / 32) 
* 4 * bmp.cy * bmp.cPlanes; 

cbBitmapInfo = sizeof (BITMAPINEO) + 
(sizeof (RGB) * (1 << bmp.cBitCount)) ; 


t 


* Allocate memory for the image data-buffer and the bitmap 


* information structure. 
*/ 


DosAllocSeg(cbBuffer, &selBuffer, SEG_NONSHARED) ; 
pbBuffer = MAKEP(selBuffer, 0); 

DosAllocSeg(cbBitmapInfo, &selBitmapInfo, SEG_NONSHARED) ; 
pbmi = MAKEP(selBitmapInfo, 0); 


/* Copy the image data. */ 
pbmi->cbFix = 12; 
pbmi->cPlanes = 1; 


pbhmi->cBitCount = 1; 
GpiQueryBitmapBits(hps, OL, (LONG) bmp.cy, pbBuffer, pbmi) ; 


GpiLoadBitmap, GpiQueryBitmapParameters, GpiSetBitmapBits 


The first bits in a scan line are stored in the most significant bits of the first byte 
of the scan line. 


GpiQueryCharDirection Change 


LONG GpiQueryCharDirection( hps) 
HPS hps; /« presentation-space handle «/ 


Parameters 


Return Value 


Errors 


The GpiQueryCharDirection function retrieves the current value of the 
character-direction attribute. This function cannot be used in an open segment 
when the drawing mode is DM_RETAIN. 


hps Identifies the presentation space. 


The return value is the current character-direction attribute if the function is suc- 
cessful, or CHDIRN_ERROR if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HPS 
PMERR_INV_IN_RETAIN_MODE 
PMERR_PS_BUSY 


PLONG adx; 
PPOINTL aptl; 


Parameters 


GpiQueryCharStringPos 171 


Comments In MS OS/2, version 1.2, the following character directions are available: 
Value Meaning 
CHDIRN_LEFTRIGHT Left to right 
CHDIRN_RIGHTLEFT Right to left 
CHDIRN_TOPBOTTOM Top to bottom 
CHDIRN_BOTTOMTOP Bottom to top 
See Also GpiSetCharDirection, GpiSetDrawingMode 
Changes Character directions other than the default are allowed. 
GpiQueryCharStringPos Correction 
BOOL GpiQueryCharStringPos( hps, flOptions, cchString, pchString, adx, apt!) 
HPS hps; /« presentation-space handle »/ 
ULONG flOptions; /« option flags »/ 
LONG cchString; _ /« length of the string »/ 
PCH pchString; /» address of string to examine »/ 


/« address of array for increment values —+/ 
/» address of array of structures for points +/ 


The GpiQueryCharStringPos function determines a position for each character 
in the string pointed to by the pchString parameter. Each position is the position 
of the character in world coordinates as if it were drawn by using the GpiChar- 
StringPos function. 


The GpiQueryCharStringPos function copies the character positions to the array 
of structures pointed to by the aptl parameter. It uses the current character attri- 
butes or the array of vector increments specified by the adx parameter to deter- 
mine the positions. The function cannot be used in an open segment when the 
drawing mode is DM_RETAIN. 


hps Identifies the presentation space. 


flOptions Specifies whether to use the vector increments specified by the adx 
parameter. It can be one of the following values: 


Value Meaning 


0 Advances the current position after each character 
by using the width of the character. The adx 
parameter is ignored. 


CHS_VECTOR Advances the current position after each character 
by using the next value in the array adx. The 
current character direction defines the direction in 
which the current position is advanced. 


cchString Specifies the length of the string pointed to by the pchString param- 
eter. 


pchString Points to the character string to examine. 
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Return Value 


Errors 


Example 


See Also 


Corrections 


adx Points to an array of increment values. Each value is a 4-byte signed 
integer specifying the distance (in world coordinates) to advance the current 
position for each character. There must be one value for each character in the 
string. The first element specifies the distance for the first character, the second 
element for the second character, and so on. This parameter may be NULL if 
the flOptions parameter is set to zero. 


aptl Points to the array of POINTL structures that receives the position (in 
world coordinates) of each character in the string. The array must be large 
enough for each character in the string, plus one final point that contains the 
position of the first character that follows the string. The POINTL structure has 
the following form: 
typedef struct _POINTL { 

LONG x; 

LONG y; 
} POINTL; 


The return value is GPL_OK if the function is successful or GPILERROR if an 
error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_CHAR_POS_OPTIONS 
PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_INV_IN_RETAIN_MODE 
PMERR_INV._LENGTH_OR_COUNT 
PMERR_INV_RECT 
PMERR_PS_BUSY 


This example calls the GpiQueryCharStringPos function to determine the loca- 
tion of each character in the string. Vector increments are not used. 


CHAR szString[] = "Sample string"; 

POINTL aptl(sizeof(szString) + 1]; 

GpiQueryCharStringPos(hps, /* presentation-space handle . 
OL, /* does not use vector increments */ 
sizeof (szString), /* number of characters in string */ 
szString, /* character string - 
NULL, /* no vector increments */ 
aptl); /* array of structures for points */ 


GpiCharStringPos, GpiQueryCharStringPosAt, GpiSetDrawingMode 


The array of points specified in the apt! parameter must include not only a 
POINTL structure for each character in the string, but also one additional 
POINTL structure that will receive the position of the first character that follows 
the string. 
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M GpiQueryDefArcParams New 
BOOL GpiQueryDefArcParams( hps, parcp) 


HPS hps; 


/» presentation-space handle »/ 


PARCPARAMS parcp; /« pointer to structure for arc parameters «/ 


Parameters 


Return Value 


The GpiQueryDefArcParams function retrieves the default arc parameters. The 
default arc parameters define the values given to the arc parameters of a presen- 
tation space whenever that presentation space is reset. (The arc parameters 
define the shape and orientation of the ellipses drawn using the arc functions.) A 
presentation space can be reset by using the GpiResetPS function. 


hps Identifies the presentation space. 


parcp Points to the ARCPARAMS structure that receives the arc parameters. 
The ARCPARAMS structure has the following form: 


typedef struct _ARCPARAMS { 
LONG 1P; 
LONG 1Q; 
LONG 1R; 
LONG 18; 
} ARCPARAMS ; 


The return value is GPILLOK if the function is successful or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 
PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_PS_BUSY 
See Also GpiQueryArcParams, GpiSetDefArcParams 
H GpiQueryDefAttrs New 
BOOL GpiQueryDefAttrs(hps, /PrimType, flAttrMask, pbunAttrs) 
HPS hps; /« presentation-space handle »/ 
LONG /PrimType; /« primitive type »/ 
ULONG ffAttrMask; /« attributes mask »/ 


PBUNDLE pbunAttrs; /« pointer to structure for default attributes »/ 


Parameters 


The GpiQueryDefAttrs function retrieves the default attributes for a primitive. 
The default attributes define the values given to a presentation space’s attributes 
when that presentation space is reset. The default attributes also define the value 
of attributes when they are explicitly set to the default by using the GpiSetAttrs 
function. 


hps Identifies the presentation space. 
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IPrimType Specifies which primitive type to retrieve attributes for. It can be 
one of the following values: 


Value Meaning 
PRIM_AREA Area primitives 
PRIM_CHAR Character primitives 
PRIM_IMAGE Image primitives 
PRIM_LINE Line and arc primitives 
PRIM_MARKER Marker primitives 


flAttrMask Specifies which attributes to retrieve. The values for this parame- 
-ter depend on the primitive type specified by the /PrimType parameter. This 
parameter can be any combination of the following values for a specific type: 


Type Values 


PRIM_AREA ABB_COLOR, ABB_BACK_COLOR, 
ABB_MIX_MODE, ABB_BACK_MIX_MODE, 
ABB_SET, ABB_SYMBOL, ABB_REF_POINT 


PRIM_CHAR CBB_COLOR, CBB_BACK_COLOR, 
CBB_MIX_MODE, CBB_BACK_MIX_MODE, 
CBB_SET, CBB_MODE, CBB_BOX, CBB_ANGLE, 
CBB_SHEAR, CBB_DIRECTION 


PRIM_IMAGE IBB_COLOR, IBB_LBACK_COLOR, IBB_MIX_MODE, 
IBB_BACK_MIX_MODE 

PRIM_LINE LBB_COLOR, LBB_MIX_MODE, LBB_WIDTH, 
LBB_GEOM_WIDTH, LBB_TYPE, LBB_END, 
LBB_JOIN 


PRIM_MARKER MBB_COLOR, MBB_BACK_COLOR, 
MBB_MIX_MODE, MBB_BACK_MIX_MODE, 
MBB_SET, MBB_SYMBOL, MBB_BOX 


If this parameter is zero, the function does not retrieve attributes but still returns 
a mask that specifies the attributes using default values. 


pbunAttrs Points to the structure that receives the default attribute values for 
each attribute specified by the flAttrMask parameter. The type of structure 
depends on the value of the /PrimType parameter; it can be one of following 


structures: 
Type Structure . 
PRIM_AREA AREABUNDLE 
PRIM_CHAR CHARBUNDLE 
PRIM_IMAGE IMAGEBUNDLE 
PRIM_LINE LINEBUNDLE 
PRIM_MARKER MARKERBUNDLE 


Return Value The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors 


See Also 
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Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_HUGE_FONTS_NOT_SUPPORTED 
PMERR_INV_BACKGROUND_COL_ATTR 
PMERR_INV_CHAR_ANGLE_ATTR 
PMERR_INV_CHAR_DIRECTION_ATTR 
PMERR_INV_CHAR_MODE_ATTR 
PMERR_INV_CHAR_SET_ATTR 
PMERR_INV_CHAR_SHEAR_ATTR 
PMERR_INV_COLOR_ATTR 
PMERR_INV_COORDINATE 
PMERR_INV_GEOM_LINE_WIDTH_ATTR 
PMERR_INV_HPS 
PMERR_INV_LINE_END_ATTR 
PMERR_INV_LINE_JOIN_ATTR 
PMERR_INV_LINE_TYPE_ATTR 
PMERR_INV_LINE_WIDTH_ATTR 
PMERR_INV_MARKER_SET_ATTR 
PMERR_INV_MARKER_SYMBOL_ATTR 
PMERR_INV_MIX_ATTR 
PMERR_INV_PATTERN_ATTR 
PMERR_INV_PATTERN_SET_ATTR 
PMERR_INV_PATTERN_SET_FONT 
PMERR_INV_PRIMITIVE_TYPE 
PMERR_PS_BUSY 
PMERR_UNSUPPORTED_ATTR 
PMERR_UNSUPPORTED_ATTR_VALUE 


GpiQueryAttrs, GpiSetDefAttrs 


GpiQueryDefTag | New 
BOOL GpiQueryDefTag(hps, p/Tag) 


HPS hps; 
PLONG piTag; 


Parameters 


Return Value 


Errors 


See Also 


/« presentation-space handle «/ 
/x pointer to tag s/ 


The GpiQueryDefTag function retrieves the default primitive tag. A primitive tag 
is a way to identify a primitive stored in a segment. 


hps Identifies the presentation space. 
plTag Points to the variable that receives the tag, 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HPS 
PMERR_INV_MICROPS_FUNCTION 
PMERR_PS_BUSY 


GpiCorrelateChain, GpiCorrelateFrom, GpiSetDefTag 
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HB GpiQueryDefViewingLimits New 
BOOL GpiQueryDefViewingLimits( hps, prc/Limits) 
HPS hps; /» presentation-space handle «/ 
PRECTL prciLimits; /» pointer to structure for viewing limits »/ 


The GpiQueryDefViewingLimits function retrieves the default viewing limits. 
The default viewing limits define the values given to a presentation space’s view- 
ing limits whenever that presentation space is reset. (The viewing limits specify a 
rectangle in model space that the system uses to clip output.) A. presentation 
space can be reset by using the GpiResetPS function. 


Parameters hps Identifies the presentation space. 


prcelLimits Points to the RECTL structure that receives the coordinates of the 
default viewing limits. The RECTL structure has the following form: 
typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


Return Value The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_COORDINATE 


PMERR_INV_HPS 
PMERR_INV_VIEWING_LIMITS 
PMERR_PS_BUSY 
See Also GpiQueryViewingLimits, GpiSetDefViewingLimits 
HM GpiQueryFontFileDescriptions Correction 
i jc dec Bitrate ha, cpt a a ee ef mae is Ardell as 
LONG GpiQueryFontFile Descriptions ( hab, pszFileName, pcFonts, pffdescs) 
HAB hab; /« anchor-block handle »/ 
PSZ pszFileName; /« address of the font-resource filename »/ 
PLONG pcFonts; /« address of variable with number of fonts «/ 
PFFDESCS pffdescs; /« array of names »/ 


The GpiQueryFontFileDescriptions function retrieves the typeface family and 
names contained in the specified file if the file is a font-resource file. The func- 
tion copies the names to the array pointed to by the pffdescs parameter. Each 
name is a null-terminated string up to 32 characters long. The function copies all 
names in the file up to the number of names specified by the pcFonts parameter. 


Parameters hab Identifies the anchor block. 


Return Value 


Example 


See Also 


Corrections 
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pszFileName Points to a null-terminated string. This string must be a valid 
MS OS/2 filename. If it does not specify a path and the .fon filename extension, 
the function appends the default extension (.d/l) and looks for the font-resource 
file in the directories specified by the libpath command in the config.sys file. 


pcFonts Points to a variable specifying the maximum number of typeface fam- 
ily and name pairs to retrieve. The function copies the actual number of descrip- 
tions it retrieved to this variable. 


pffdescs Points to the array to receive the typeface family and names for each 
font. Each array element is itself a two-element array of type FFDESCS. 


The return value is the number of fonts for which details were not returned if 
the function is successful or GPILALTERROR if an error occurred. 


This example uses the GpiQueryFontFileDescriptions to retrieve the typeface 
family and names for the fonts in the helv.dll file. The function is called twice, 
once to determine the actual number of fonts in the file, and again to retrieve 
the descriptions. 

PFFDESCS pffdescs; 

SEL sel; 

LONG cFonts = QO; 

/* Retrieve a count of all fonts in the file. */ 

cFonts = GpiQueryFontFileDescriptions(hab, "helv", &cFonts, NULL); 
/* Allocate space for the descriptions. */ 


DosAllocSeg((USHORT) (cFonts * sizeof(FFDESCS)), &sel, SEG_NONSHARED) ; 
pffdescs = MAKEP(sel, 0); 


/* Retrieve the descriptions. */ 


GpiQueryFontFileDescriptions(hab, "“"helv", &cFonts, pffdescs) ; 
GpiQueryFonts 


In the example, the function retrieves information from the helv.dil file, not the 
helv.fon file. If no path and filename extension are given, the function by default 
searches for a file that has the .di/l extension. Also, the cFonts variable must be 
set to zero for the first call to the function. 


- GpiQueryMetaFileBits Correction 


BOOL GpiQueryMetaFileBits( hmf, off, cbBuffer, pbBuffer) 


HMF hmf; 
LONG off; 
LONG cbBuffer; 
PBYTE pbBuffer; 


/» metafile handle »/ 
/« offset to the first metafile byte to copy «/ 
/« length in bytes of buffer »/ 
/« address of buffer for metafile data »/ 


The GpiQueryMetaFileBits function copies data from the metafile specified by 
hmf to the buffer pointed to by the pbBuffer parameter. The function copies the 
bytes of the metafile, up to the number of bytes specified by cbBuffer, starting at 


the byte whose offset from the beginning of the metafile is specified by the off 
parameter. 
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Parameters 


Return Value 


Errors 


Example 


See Also 


Corrections 
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hmf Identifies the memory metafile. 


off Specifies the offset in bytes from the beginning of the metafile to the first 
byte to copy. 


cbBuffer Specifies the number of bytes of metafile data to copy. 


pbBuffer Points to the buffer to receive the metafile data. It must have the 
number of bytes specified by the cbBuffer parameter. 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HMF 
PMERR_INV_METAFILE_LENGTH 
PMERR_INV_METAFILE_OFFSET 


This example uses the GpiQueryMetaFileBits function to retrieve the graphics- 
order data from the specified metafile. The GpiQueryMetaFileLength function 
returns the length of the metafile. 

HME hmf; 

LONG cBytes; 


SEL sel; 
LONG off; 


hmf = GpiLoadMetaFile(hps, "sample.met") ; 
/* Allocate the buffer for the metafile data. */ 


DosAllocSeg(0, &sel, SEG_NONSHARED) ; 
pbBuffer = MAKEP(sel, 0); 


cBytes = GpiQueryMetaFileLength(hmf); /* gets length of metafile */ 
/* Retrieve up to 64K. */ 


GpiQueryMetaFileBits ( ; 
hmf, /* handle of metafile */ 


off, /* offset of next byte to retrieve */ 
65536L, /* retrieves as much as possible a/ 
pbBuf fer) ; /* buffer to receive metafile data */ 


GpiQueryMetaFileLength, GpiSetMetaFileBits 


In the example, the first parameter of the GpiQueryMetaFileBits function is a 
handle of the metafile, not a handle to the presentation space. Also, the metafile 
is assumed to be no greater than 64K. For larger metafiles, you can use the 
DosAllocHuge function to allocate segments to receive the metafile bits. 


Change 


BOOL GpiResetPS( hps, flOption) 


HPS hps; 
ULONG flOption; 


/« presentation-space handle :/ 
/« reset option »/ 


The GpiResetPS function resets the presentation space. In general, resetting the 
presentation space restores attributes to their default values—that is, the values 
given to the attributes when the presentation space was created or the values 


Parameters 


Return Value 


Errors 


See Also 
Changes 


Corrections 
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specified in the last call to the GpiSetDefAttrs function. The function can reset 
the presentation space in three ways: as if a segment were closed; as if the 
presentation space had just been created, but without deleting any resources; 
and as if the presentation space had just been created. It uses the flOption 
parameter to determine how to reset the presentation space. 


The GpiResetPS function does not draw or erase the device. It is up to the 
application to erase the screen, if this is required. Also, the function does not 
affect the association between the specified presentation space and a device con- 
text. 


The GpiResetPS function also deselects a bitmap if any are selected into a 
memory device context. 


hps Identifies the presentation space. 


flOption Specifies the reset option. It can be one of the following: 
Value Meaning 


GRES_ATTRS Sets all current attributes to their default values, 
the current model transform to unity, and the 
current position to (0,0). The option also ends any 
open path, area, or element brackets and closes 
any open segment. Finally, it sets the current clip 
path and viewing limits to their widest possible 
values. 


GRES_SEGMENTS Resets as described for GRES_ATTRS, plus it 
deletes all retained segments, clears any boundary 
data, releases the clip region (if any), enables kern- 
ing (if the device supports it), and sets the default 
values for initial segment attributes, default viewing 
transform, graphics field, drawing mode, draw con- 
trols, edit mode, and attribute mode. 


GRES_ALL Resets as described for GRES_ATTRS and 
GRES_SEGMENTS, plus it deletes any logical 
fonts and local identifiers for bitmaps and sets the 
logical color table to its default value. 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error Occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HPS 
PMERR_INV_RESET_OPTIONS 
PMERR_PS_BUSY 


GpiAssociate, GpiCreatePS, GpiSetAttrs 


Calling GpiResetPS resets the attributes of the presentation space to the values 
it had when created or to the values specified in the last call to GpiSetDefAttrs. 


GpiResetPS also deselects a bitmap if any are selected into a memory device 
context. 
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™ GpiRotate 


BOOL GpiRotate( hps, pmatif, flType, fxAngle, ppt!) 


HPS hps; 
PMATRIXLF pmatif; 
LONG flType; 
FIXED fxAngle; 
PPOINTL ppt; 


Parameters 


Return Value 


New 
/« presentation-space handle »/ 
/» pointer to structure with matrix s/ 
/« transformation type »/ 


/» pointer to variable with rotation angle »/ 
/« pointer to structure with center point »/ 


The GpiRotate function creates a transformation that can be used to rotate 
objects around a given point. GpiRotate either adds the specified rotation to an 
existing transformation or replaces the existing transformation with the rotation. 
The new transformation can be used in a subsequent call to any transformation 
function. 


hps Identifies the presentation space. 


pmatlf Points to the MATRIXLF structure that contains the transformation 
matrix. The MATRIXLEF structure has following form: 


typedef struct _MATRIXLF { 
FIXED f£xM11; 
FIXED f£xM12; 
LONG 1M13; 
FIXED f£xM21; 
FIXED £xM22; 


LONG 1M23; 
LONG 1M31; 
LONG 1M32; 
LONG 1M33; 

} MATRIXLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
fiType Specifies how the specified matrix should be used to modify the 
transformation. It can be one of the following values: 

Value Meaning 


TRANSFORM_ADD Additive. The specified transformation matrix is 
combined with the existing transformation, with 
the existing transformation first, the new 
transformation second. This option is useful for 
incremental updates to transformations. 


TRANSFORM_REPLACE _ New/replace. The previous transformation is dis- 
carded and replaced by the specified transforma- 
tion matrix. 

fxAngle Specifies the rotation (in degrees) to use. 


pptl Points to the POINTL structure that contains the coordinates of a point, 
relative to the origin, that defines the center of rotation. The POINTL structure 
has the following form: 


typedef struct _POINTL { 


LONG x; 
LONG y; 
} POINTL; 


The return value is GPIL_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors 


See Also 


GpiScale 
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Use the WinGetLastError function to retrieve the error value, which may be the 
following: 


PMERR_INV_TRANSFORM_TYPE 


GpiScale, GpiSetDefault ViewMatrix, GpiSetModelTransformMatrix, 
GpiSetSegmentTransformMatrix, GpiSet ViewingTransformMatrix, 
GpiTranslate 


BOOL GpiScale(hps, pmatif, fiType, afxScale, ppt!) 


HPS hps; 
PMATRIXLF pmatif; 
LONG fiType; 
PFIXED afxScale; 
PPOINTL ppt: 


Parameters 


New 
/« presentation-space handle * a/ 
/« pointer to structure for matrix »/ 
/« transformation type «/ 


/« pointer to variable with scaling factor «/ 
/« pointer to structure with point data —s «/ 


The GpiScale function creates a transformation that can be used to scale 
(expand or contract) an object relative to a given point. GpiScale either adds the 
specified scaling factor to an existing transformation or replaces the existing 
transformation. The new transformation can be used in a subsequent call to any 
transformation function. 


hps_ Identifies the presentation space. 


pmatlf Points to the MATRIXLF structure that contains the transformation 
matrix. The MATRIXLF structure has the following form: 


typedef struct _MATRIXLF { 
FIXED £xM11; 
FIXED f£xM12; 
LONG 1M13; 
FIXED fxM21; 
FIXED f£xM22; 


LONG 1M23; 

LONG 1M31; 

LONG) 1M32; 

LONG 1M33; 
} MATRIXLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


fiType Specifies how a specified matrix should be used to modify the transfor- 
mation. It can be one of the following values: 


Value - Meaning 


TRANSFORM_ADD Additive. The specified transformation matrix is 
combined with the existing transformation, with 
the existing transformation first, the new 
transformation second. This option is useful for 
incremental updates to transformations. 


TRANSFORM_REPLACE — New/replace. The previous transformation is dis- 
carded and replaced by the specified transforma- 
tion matrix. 
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afxScale Points to the two-element array that contains the scaling factors to 
use. The first element specifies the scaling factor along the x-axis; the second 
specifies the scaling factor along the y-axis. 


pptl Points to the POINTL structure that contains the coordinates of the 
point, relative to the origin, that defines the center of the scale. The POINTL 
structure has the following form: 
typedef struct _POINTL { 

LONG x; 


LONG 
} POINTL; 


Return Value The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be the 
following: 
PMERR_INV_TRANSFORM_TYPE 

See Also GpiRotate, GpiSetDefault ViewMatrix, GpiSetModelTransformMatrix, 
GpiSetSegmentTransformMatrix, GpiSet ViewingTransformMatrix, 
GpiTranslate 

GpiSetCharDirection Change 

BOOL GpiSetCharDirection( hps, flDirection) 

HPS hps; /« presentation-space handle «/ 

LONG flDirection; /« character direction »/ 


The GpiSetCharDirection function sets the character direction for drawing char- 
acters. The character direction specifies the direction to advance after drawing a 
character, relative to the baseline. 


If the attribute mode is AM_PRESERVE, the function saves the previous char- 
acter direction on the attribute stack when it sets the new direction. The previ- 
ous character direction can be retrieved by using the GpiPop function. 


Parameters hps Identifies the presentation space. 


flDirection Specifies the character direction. This parameter can be one of 
the following values: 


Value Meaning 
CHDIRN_DEFAULT Default direction (left to right) 
CHDIRN_LEFTRIGHT Left to right 
CHDIRN_RIGHTLEFT Right to left 
CHDIRN_TOPBOTTOM Top to bottom 
CHDIRN_BOTTOMTOP Bottom to top 


Return Value The return value is GPI_LOK if the function is successful or GPI_LERROR if an 
error occurs. 
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Use the WinGetLastError function to retrieve the error value, which may be one 


Errors 
of the following: 
PMERR_INV_CHAR_DIRECTION_ATTR 
PMERR_INV_HPS 
PMERR_PS_BUSY | 
See Also GpiPop, GpiQueryCharDirection, GpiSetAttrMode, GpiSetAttrs 
Changes The following character directions can now be specified for the flDirection 
parameter: 
Value Meaning 
CHDIRN_DEFAULT Default direction 
CHDIRN_LEFTRIGHT Left to right 
CHDIRN_RIGHTLEFT Right to left 
CHDIRN_TOPBOTTOM Top to bottom 
CHDIRN_BOTTOMTOP Bottom to top 
m@ GpiSetDefArcParams New 


BOOL GpiSetDefArcParams( hps, parcp) 


HPS hps; 


/» presentation-space handle »/ 


PARCPARAMS parcp; /« pointer to structure with arc parameters »«/ 


Parameters 


Return Value 


Errors 


The GpiSetDefArcParams function sets the default arc parameters. The default 
arc parameters define the values given to the arc parameters of a presentation 
space whenever that presentation space is reset. (The arc parameters define the 
shape and orientation of the ellipses drawn using the arc functions.) A presenta- 
tion space can be reset using the GpiResetPS function. 


hps Identifies the presentation space. 


parcp Points to the ARCPARAMS structure that contains the arc parameters. 


The ARCPARAMS structure has the following form: 


typedef struct _ARCPARAMS { 
LONG 1P; 
LONG 1Q; 
LONG 1R; 
LONG 1S; 
} ARCPARAMS; 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_PS_BUSY 
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Comments Setting the default arc parameters does not immediately affect the arc parame- 
ters. The system uses the default arc parameters only when the presentation 
space is reset. The default arc parameters are reset when the presentation space 
is reset using the GRES_SEGMENT or GRES_ALL options of the GpiResetPS 
function. The reset values for the default arc parameters are IP=1, 1Q=1, IR=0, 


and 1S=0. 
See Also GpiFullArc, GpiPartialArc, GpiPointArc, GpiQueryDefArcParams 
GpiSetDefAttrs New 
BOOL GpiSetDefaAttrs (hps, /PrimType, flAttrMask, pbunAttrs) 
HPS hps; /»« presentation-space handle »/ 
LONG /PrimType; /« primitive type »/ 
ULONG ffAttrMask; /» attributes mask »/ 


PBUNDLE pbunAttrs; /« pointer to structure with default attributes »/ 


The GpiSetDefAttrs function sets the default attributes for a primitive. The 

- default attributes define the values given to the attributes of a presentation space 
when that presentation space is reset. The default attributes also define the value 
of attributes when they are explicitly set to the default using the GpiSetAttrs 
function. 


Parameters hps Identifies the presentation space. 


IPrimType Specifies which primitive type to set default attributes for. It can 
be one of the following values: 


Value Meaning 
PRIM_AREA Area primitives 
PRIM_CHAR Character primitives 
PRIM_IMAGE Image primitives 
PRIM_LINE Line and arc primitives 
PRIM_MARKER Marker primitives 


fiAttrMask — Specifies which default attributes to set. The values for this 
parameter depend on the primitive type specified by the /PrimType parameter. 
This parameter can be any combination of the following values for a specific 


type: 
Type Values 
PRIM_AREA ABB_COLOR, ABB_BACK_COLOR, 


ABB_MIX_MODE, ABB_BACK_MIX_MODE, 
ABB_SET, ABB_SYMBOL, 
ABB_REF_POINT 


PRIM_CHAR CBB_COLOR, CBB_BACK_COLOR, 
CBB_MIX_MODE, CBB_BACK_MIX_MODE, 
CBB_SET, CBB_MODE, CBB_BOX, 
CBB_ANGLE, CBB_SHEAR, 
CBB_DIRECTION 


Return Value 


Errors 
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Type Values 

PRIM_IMAGE IBB_COLOR, IBB_.BACK_COLOR, 
IBB_MIX_MODE, IBB_BACK_MIX_MODE 

PRIM_LINE LBB_COLOR, LBB_MIX_MODE, 


LBB_WIDTH, LBB_GEOM_WIDTH, 
LBB_TYPE, LBB_LEND, LBB_JOIN 


PRIM_MARKER MBB_COLOR, MBB.BACK_COLOR, 
MBB_BACK_MIX_MODE, MBB_SET, 
MBB_SYMBOL, MBB_BOX, 
MBB_MIX_MODE 


If this parameter is zero, no attributes are set, regardless of the value of the 
pbunAttrs parameter. 


pbunAttrs Points to the buffer that contains attribute values for each default 
attribute specified by the flAttrMask parameter. The buffer format depends on 


the primitive type specified by the /PrimType parameter. The following structures 
can be used for the specified primitive types: . 


Type Structure 
PRIM_AREA AREABUNDLE 
PRIM_CHAR CHARBUNDLE 
PRIM_IMAGE IMAGEBUNDLE 
PRIM_LINE LINEBUNDLE 
PRIM_MARKER MARKERBUNDLE 


The return value is GPI_OK if the function is successful or GPLLERROR if an 
error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_HUGE_FONTS_NOT_SUPPORTED 
PMERR_INV_BACKGROUND_COL_ATTR 
PMERR_INV_CHAR_ANGLE_ATTR 
PMERR_INV_CHAR_DIRECTION_ATTR 
PMERR_INV_CHAR_MODE_ATTR 
PMERR_INV_CHAR_SET_ATTR 
PMERR_INV_CHAR_SHEAR_ATTR 
PMERR_INV_COLOR_ATTR 
PMERR_INV_COORDINATE 
PMERR_INV_GEOM_LINE_WIDTH_ATTR 
PMERR_INV_HPS 
PMERR_INV_LINE_END_ATTR 
PMERR_INV_LINE_JOIN_ATTR 
PMERR_INV_LINE_TYPE_ATTR 
PMERR_INV_LINE_WIDTH_ATTR 
PMERR_INV_MARKER_SET_ATTR 
PMERR_INV_MARKER_SYMBOL_ATTR 
PMERR_INV_MIX_ATTR 
PMERR_INV_PATTERN_ATTR 
PMERR_INV_PATTERN_SET_ATTR 
PMERR_INV_PATTERN_SET_FONT 
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PMERR_INV_PRIMITIVE_TYPE 
PMERR_PS_BUSY 
PMERR_UNSUPPORTED_ATTR 
PMERR_UNSUPPORTED_ATTR_VALUE 


Comments Setting the default attributes for a primitive does not immediately affect the 
current attributes. The system uses the default attributes only when the presenta- 
tion space is reset or when the GpiSetAttrs function is used to set the defaults. 
The default attributes are reset when the presentation space is reset using the 
GRES_SEGMENT or GRES_ALL options of the GpiResetPS function. 


If an attempt is made to set an invalid default value, none of the specified 
default attribute values change. Some invalid default attribute values (for exam- 
ple, certain color and mix values), however, may not be detected until the attri- 
bute is used. 


See Also GpiQueryDefAttrs, GpiSetAttrs 


GpiSetDefTag New 


BOOL GpiSetDefTag( hps, /Tag) 
HPS hps; /» presentation-space handle »/ 
LONG /Tag; /s tag »/ 


The GpiSetDefTag function sets the default primitive tag. A primitive tag is a 

way to identify a primitive stored in a segment. This function sets the default 

primitive tag and the system applies this tag to all subsequent primitives. 
Parameters hps Identifies the presentation space. 


lTag Specifies the tag. It must be an integer value. 


Return Value The return value is GPL_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be the 
following: 
PMERR_LINV_HPS 
PMERR_INV_MICROPS_FUNCTION 
PMERR_PS_BUSY 
See Also GpiCorrelateChain, GpiCorrelateFrom, GpiCorrelateSegment, 
GpiQueryDefTag : 
GpiSetDefViewingLimits New 
BOOL GpiSetDefViewingLimits(hps, prciLimits) 
HPS hps; /« presentation-space handle s/ 


PRECTL prciLimits; /» pointer to structure with viewing limits »/ 


The GpiSetDefViewingLimits function sets the default viewing limits. The default 
viewing limits define the values given to the viewing limits of a presentation 
space whenever that presentation space is reset. (The viewing limits specify a 
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rectangle in model space that the system uses to clip output.) A presentation 
space can be reset using the GpiResetPS function. 


Parameters hps Identifies the presentation space. 


prclLimits Points to the RECTL structure that contains the coordinates of the 
default viewing limits. The RECTL structure has the following form: 


typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


Return Value The return value is GPI_OK if the function is successful or GPLLERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_INV_VIEWING_LIMITS 
PMERR_PS_BUSY . 


Comments Setting the default viewing limits does not immediately affect the viewing-limits 
parameters. The system uses the default viewing limits only when the presenta- 
tion space is reset. The default viewing limits are reset when the presentation 
space is reset using the GRES_SEGMENT or GRES_ALL options of the 
GpiResetPS function. The reset values for the default viewing limits are all of 
model space, meaning nothing is clipped. 


See Also GpiQueryDefViewingLimits, GpiSetViewingLimits 


GpiSetPS Correction | 
BOOL GpiSetPS( hps, psizi, flOptions) 

HPS hps; /« presentation-space handle »/ 

PSIZEL psizi; /« address of structure for presentation-space size «/ 

ULONG flOptions; /« options »/ 


The GpiSetPS function sets the page size and units for the presentation space. | 
This function is often used to change the device transformation for the presenta- 
tion space. 


Parameters hps Identifies the presentation space. 


psizl Points to the SIZEL structure that contains the size of the presentation 
space. The SIZEL structure has the following form: 


typedef struct _SIZEL { 
LONG cx; 
LONG cy; 

} SIZEL; 
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flOptions Specifies the presentation-space options. The options define the 
page unit for the presentation space. Although the ffOptions parameter can 
include many other options (as specified by the GpiCreatePS function), the 
GpiSetPS function ignores all but the following options: 


Option ; Meaning 
PU_ARBITRARY Sets the page units to pels, but permits the units to 
. be modified later by using the GpiSetPageViewport 

function. 

PU_HIENGLISH Sets the units to 0.001 inch. 

PU_HIMETRIC Sets the units to 0.01 millimeter. 

PU_LOENGLISH Sets the units to 0.01 inch. 

PU_LOMETRIC Sets the units to 0.1 millimeter. 

PU_PELS Sets the units to pels. 

PU_TWIPS Sets the units to 1/1440 inch (1/20 point). 

GPIF_DEFAULT Specifies that coordinates are stored as 4-byte 
integers (LONG). This value is the same as 
GPIF_LONG. 

GPIF_SHORT Specifies that coordinates are stored as 2-byte 
integers. _ 

GPIF_LONG Specifies that coordinates are stored as 4-byte 
integers. 

-PS_NORESET Specifies that the presentation space cannot be 


fully reset, and that a reset equivalent to 
GRES_SEGMENTS is performed. (Otherwise, a 
full reset, equivalent to GRES_ALL, is Ber. 
formed.) 


Return Value The return value is GPI_OK if the function is successiul or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_HDC 

PMERR_INV_HPS 
PMERR_INV_OR_INCOMPAT_OPTIONS 
PMERR_INV_PS 

PMERR_PS_BUSY 


Comments The GpiSetPS function does not affect the device context associated with the 
presentation space. This means the device context already associated remains 
associated. Also, the function does not change the type of presentation space. 
(Presentation-space types include the micro-presentation space and the normal 
presentation space.) 


When this function is called, it resets the presentation space to a state that is 
equivalent to setting the value GRES_ALL in the GpiResetPS function. 
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See Also GpiCreatePS, GpiResetPS 

Corrections GpiSetPS can be used to set the storage format for the presentation space 
by specifying one of the constants GPIF_DEFAULT, GPIF_LONG, or 
GPIF_SHORT. The PS_NORESET constant prevents the presentation space 
from being completely reset. 

GpiSetViewingLimits Correction 


BOOL GpiSetViewingLimits( hps, prciLimits ) 


HPS hps; 
PRECTL prciLimits; 


Parameters 


Return Value 


Errors 


Comments 


/» presentation-space handle »/ 
/» address of structure with viewing limits »/ 


The GpiSetViewingLimits function sets the viewing limits. The viewing limits 
specify a rectangle in model space that the system uses to clip output. The view- 
ing limits include all points inside the rectangle and all points on the left and _ 
bottom edges, but do not include points on the right and top edges. Points on 
these edges are clipped. 


The GpiSetViewingLimits function can be used in a segment to set the viewing 
limits for subsequent primitives in the segment. The viewing limits also apply to 
any called segments, unless the called segment itself sets the viewing limits. 


hps Identifies the presentation space. 


prelLimits Points to the RECTL structure that contains the coordinates of the 
viewing limits. The RECTL structure has the following form: 
typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INV_COORDINATE 
PMERR_INV_HPS 
PMERR_INV_VIEWING_LIMITS 
PMERR_PS_BUSY 


Unless the segments in the picture chain have the fast-chaining attribute, the sys- 


_ tem resets the default viewing limits when each segment in the chain is drawn. 


The default viewing limits include all model space—that is, nothing is clipped. 


The segment and model transformations do not affect the viewing limits, but the 
viewing limits are affected by the current viewing and default viewing transforma- 
tions. 


If either the left boundary is greater than the right or the bottom boundary is 
greater than the top, a NULL rectangle is defined, and all points are clipped. 


See Also 


Corrections 


GpiTranslate 
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GpiQueryViewingLimits, GpiSetAttrMode 


If either the left boundary is greater than the right or the bottom boundary is 
greater than the top, a NULL rectangle is defined, and all points are clipped. 


BOOL GpiTranslate( hps, pmatif, flType, ppt!) 


HPS hps; 
PMATRIXLF pmatif; 
LONG flType; 
PPOINTL ppt; 


Parameters 


New 
/« presentation-space handle »/ 
/« pointer to structure with matrix s/ 
/« transformation type s/ 


/« pointer to structure with point data »/ 


The GpiTranslate function creates a transformation that can be used to translate 
(move) an object a specified direction and distance. GpiTranslate either adds 
the specified translation to an existing transformation or replaces the existing 
transformation. The new transformation can be used in a subsequent call to any 
transformation function. 


hps Identifies the presentation space. 


pmatlf Points to the MATRIXLF structure that contains the transformation 
matrix. The MATRIXLF structure has the following form: 


typedef struct _MATRIXLF { 
FIXED f£xM11; 
FIXED £xM12; 
LONG 1M13; 
FIXED fxM21; 
FIXED f£xM22; 


LONG 1M23; 

LONG 1M31; 

LONG 1M32; 

LONG) 1M33; 
} MATRIXLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


fiType Specifies how a specified matrix should be used to modify the transfor- 
mation. It can be one of the following values: 


Value - Meaning 


TRANSFORM_ADD Additive. The specified transformation matrix is 
combined with the existing transformation, with 
the existing transformation first, the new 
transformation second. This option is useful for 
incremental updates to transformations. 


TRANSFORM_REPLACE — New/replace. The previous transformation is dis- 
carded and replaced by the specified transforma- 
tion matrix. 


pptl Points to the POINTL structure that contains the coordinates of a point, 
relative to the origin, that defines the required translation. The POINTL struc- 
ture has the following form: 


typedef struct _POINTL { 
LONG x; 
LONG y; 

} POINTL; 


Return Value 
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The return value is GPI_OK if the function is successful or GPILERROR if an 
error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be the 
following: 
PMERR_INV_TRANSFORM_TYPE 

See Also GpiRotate, GpiScale, GpiSetDefault ViewMatrix, GpiSetModelTransform- 
Matrix, GpiSetSegmentTransformMatrix, GpiSet ViewingTransformMatrix 

GpiUnloadFonts Correction | 


BOOL GpiUnloadFonts( hab, pszModName) 


HAB hab; 


PSZ pszModName; 


Parameters 


Return Value 


Errors 


See Also 


Corrections 


/« anchor-block handle »/ 
/» address of the module name «/ 


The GpiUnloadFonts function unloads font definitions that were previously 
loaded from the resource file specified by the pszModName parameter. Before 
unloading fonts, the application must delete any local identifiers previously 
assigned to the fonts. The function unloads the fonts for the application only. If 
any other applications have loaded the fonts, they remain available for those 


- applications. 


hab Identifies the anchor block. 


pszModName Points to a null-terminated string. This string must be a valid 
MS OS/2 filename. If it does not specify a path and the filename extension, the 
function appends the default extension (.dil) and searches for the font resource 
file in the directories specified by the libpath command in the config.sys file. 


The return value is GPI_OK if the function is successful or GPL_LERROR if an 
error occurred. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_FONT_FILE_NOT_LOADED 
PMERR_FONT_NOT_LOADED 
PMERR_OWN_SET_ID_REFS 


GpiCreateLogFont, GpiDeleteSetId, GpiLoadFonts, GpiSetCharSet 


Before unloading fonts, the application must delete any local identifiers previ- 
ously assigned to the fonts. 
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GpiWCBitBIt 


HPS hps; 
HBITMAP hbm; 
LONG cPoints; 
PPOINTL apti; 
LONG /Rop; 


Correction 
LONG GpiWCBIitBIt( hps, hbm, cPoints, apti, [Rop, flOptions) 
/» presentation-space handle »/ 
/x bitmap handle . -s/ 
/« number of points s/ 
/« address of structure with points «/ 
/« mixing function »/ 
/« options »/ 


ULONG /flOptions; 


Parameters 


The GpiWCBitBlt function copies a bitmap to a presentation space. It can also 
modify the bitmap within a rectangle in a presentation space. The exact opera- 
tion carried out by GpiWCBitBlt depends on the raster operation specified by 
the /Rop parameter. 


If /Rop directs GpiWCBitBIt to copy a bitmap, the function copies the bitmap 
specified by hbm to the presentation space. The presentation space must be 
associated with a device context for the display, for memory, or for some other 
suitable raster device. The apf] parameter points to an array of points that 
specify the corners of a rectangle in the bitmap as well as the corners of the 
rectangle in the presentation space to receive the bitmap. The bitmap rectangle 
is specified in device coordinates; the presentation-space rectangle in world coor- 
dinates. If the bitmap and presentation-space rectangles are not the same (after 
converting the presentation space to device coordinates), GpiWCBitBlt stretches 
or compresses the bitmap to fit the presentation-space rectangle. 


If [Rop directs GpiWCBitBlt to modify a bitmap, the function uses the raster 
operation to determine how to alter the bits in a rectangle in the presentation 
space. Raster operations include changes such as inverting existing bits, replac- 
ing bits with pattern bits, and mixing existing and pattern bits to create new 
colors. For some raster operations, the function mixes the bits of the bitmap 
with the presentation space and/or pattern bits. 


hps Identifies the presentation space. 
hbm Identifies the bitmap. 


cPoints Specifies the number of points pointed to by the aptl parameter. It 
must be 4. 


aptl Points to an array of POINTL structures that contains the number of 
points specified in the cPoints parameter. The points must be given in the follow- 
ing order: 
Element index Coordinate 
0 Specifies the lower-left corner of the target rectangle in 
world coordinates. 


1 Specifies the upper-right corner of the target rectangle in 
world coordinates. 


2 Specifies the lower-left corner of the source rectangle in 
device coordinates. 


3 Specifies the upper-right corner of the source rectangle in 
device coordinates. 
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The POINTL structure has the following form: 
typedef struct TPOINTL { 


LONG x; 
LONG y; 
} POINTL; 


lRop Specifies the raster operation for the function. It can be any value in the 
range O through 255 or one of the following values, which represent common ras- 
ter operations: 


Value 


ROP_DSTINVERT 
ROP_MERGECOPY 


ROP_MERGEPAINT 
ROP_NOTSRCCOPY 


ROP_NOTSRCERASE 


ROP_ONE 
ROP_PATCOPY 
ROP_PATINVERT 


ROP_PATPAINT 
ROP_SRCAND 


ROP_SRCCOPY 
ROP_SRCERASE 


ROP_SRCINVERT 
ROP_SRCPAINT 


ROP_ZERO 


Value 


BBO_AND 


BBO_OR 


Meaning 


Inverts the target. 


Combines the source and the pattern using the 
bitwise AND operator. 


Combines the inverse of the source and the tar- 


get using the bitwise OR operator. 


Copies the inverse of the source to the target. 


Combines the inverse of the source and the 
inverse of the target bitmaps using the bitwise 
AND operator. 


Sets all target pels to 1. 
Copies the pattern to the target. 


Combines the target and the pattern using the 
bitwise exclusive XOR operator. 


Combines the inverse of the source, the pattern, 
and target using the bitwise OR operator. 


Combines the source and target bitmaps using 
the bitwise AND operator. 


Copies the source bitmap to the target. 


Combines the source and the inverse of the tar- 
get bitmaps using the bitwise AND operator. 


Combines the source and target bitmaps using 
the bitwise exclusive OR operator. 


Combines the source and target bitmaps using 
the bitwise OR operator. 


Sets all target pels to 0. 


Meaning 


Compresses two rows or columns into one by 
combining them with the bitwise AND operator. 
This value is useful for compressing bitmaps that 
have black images on a white background. 


Compresses two rows or columns into one by 
combining them with the bitwise OR operator. 
This value is the default and is useful for 
compressing bitmaps that have white images on 
a black background. 


flOptions Specifies how to compress a bitmap if the target rectangle is smaller 
than the source. It can be one of the following values: 
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Return Value 


Errors 


Comments 


Example 


Value Meaning 


BBO_IGNORE Compresses two rows or columns by throwing 
one out. This value is useful for compressing 
color bitmaps. 


All values in the range 0x0100 to OxFFO0 are reserved for privately supported 
modes for particular devices. 


The return value is GPILOK or GPI_HITS if the function is successful (it is 
GPLHITS if the detectable attribute is set for the presentation space and a 
correlation hit occurs). The return value is GPILERROR if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_BASE_ERROR 
PMERR_BITMAP_NOT_SELECTED 
PMERR_INCOMPATIBLE_BITMAP 
PMERR_INV_BITBLT_MIX 
PMERR_INV_BITBLT_STYLE 
PMERR_INV_COORDINATE 
PMERR_INV_DC_TYPE 
PMERR_INV_HBITMAP 
PMERR_INV_HDC 
PMERR_INV_LIN_AREA 
PMERR_INV_IN_PATH 
PMERR_INV_LENGTH_OR_COUNT 


The GpiWCBitBit function can be used in an open segment. If the drawing 
mode is DU_DRAWANDRETAIN or DM_RETAITN, the function builds a 
graphics order in the current open segment. The order identifies the bitmap han- 
dle arid uses uses long or short coordinates, as determined by the presentation- 
space format. 


GpiWCBitBit does not affect the pels in the upper and right boundaries of the 
presentation-space rectangle. This means the function draws up to but does not 
include those pels. Also, the function ignores any rotation transformations. 


If the /Rop parameter includes a pattern, GpiWCBitBlt uses the current area 
color, area background color, pattern set, and pattern symbol of the presenta- 
tion space. Although the function may stretch or compress the bitmap, it never 
stretches or compresses the pattern. 


If the presentation-space and the bitmap have different color formats, 
GpiWCBitBlt converts the bitmap color format. as it copies the bitmap. This 
applies to bitmaps copied to a device context having a monochrome format. To 
convert a monochrome bitmap to a color bitmap, GpiWCBitBlt converts 1 pels 
to the presentation foreground color, and 0 pels to the current-area backsroune 
color. 


This example uses GpiWCBitBit to copy and compress a bitmap in a presenta- 
tion space. The function copies the bitmap that is 100 pels wide and 100 pels 
high into a 50-by-50-pel rectangle at the location (300,400). Since the raster 
operation is ROP_SRCCOPY, GpiWCBitBlt replaces the image previously in 
the presentation-space rectangle. The function compresses the bitmap to fit the 
new rectangle by discarding extra rows and columns as specified by the 
BBO_IGNORE option. 
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HPS hps; 
HBITMAP hbm; 
POINTL aptl[4]) ={ 
300, 400, /* lower-left corner of target */ 
350, 450, /* upper-right corner of target a/ 
Oo, O, /* lower-left corner of source */ 
100, 100 }; /* upper-right corner of source */ 
GpiWCBitBlt(hps, /* presentation space */ 
hbm, /* bitmap handle */ 
4L, /* four points needed to compress * 
aptl, 7* points for source and target rectangles */ 
ROP_SRCCOPY, /* copy source replacing target * 
BBO_IGNORE) ; /* discard extra rows and columns a/ 
See Also DevOpenDC, GpiBitBlt, GpiCreateBitmap, GpiLoadBitmap, GpiSetBitmap, 
GpiSetBitmapDimension, GpiSetBitmapId 
Corrections For the apil parameter, the element indexes are 0, 1, 2, and 3. The array has at 
most four elements, not five. 
HM_ACTIONBAR_COMMAND New 
HM_ACTIONBAR_COMMAND 
usCmd = (USHORT) SHORT1FROMMP (mp1); /* command value */ 
The HM_ACTIONBAR_COMMAND message is sent when the user chooses a 
command from an application-supplied menu in the help window. The applica- 
tion should carry out the command identified by the usCmd parameter. 
Parameters usCmd_ Low word of mp1. Specifies the command value. 


Return Value 


Comments 


See Also 


An application should return zero if it processes this message. 


Applications can replace the menu in a help window by specifying a menu ID in 
the HELPINIT structure used when the help instance is created by using the 
WinCreateHelpInstance function. If an application replaces the menu, it 
receives the HM_ACTIONBAR_COMMAND message when the user chooses a 
command from the menu. Application-supplied menus should have command 
values in the range 0x7F00 through Ox7FFF. 


WinCreateHelpInstance 


HM_CREATE_HELP_TABLE New 


Parameters 


HM_CREATE_HELP_TABLE 
mpl = MPFROMP((PHELPTABLE) phtHelpTable); /* pointer to help table */ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an HM_CREATE_HELP_TABLE message to a help win- 
dow to set the help table for the help instance. The system uses the specified 
help table to locate help-panel IDs on subsequent requests for help. 


phtHelpTable Low and high word of mp1. Points to the HELPTABLE struc- 
ture that contains the help-table information. The HELPTABLE structure has 
the following form: 
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Return Value 
Comments 


See Also 


typedef struct  HELPTABLE { 
USHORT idAppWindow; 
PHELPSUBTABLE phstHelpSubTable; 
USHORT idExtPanel;” 

} HELPTABLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
The return value is FALSE. | 


An application can use this message to replace the initial help table of a help. 
instance or to set the table if no initial help table is given. The initial help table 
is specified in the HELPINIT structure used when the help instance is created by 
using the WinCreateHelpInstance function. This message replaces the help table 
without freeing any memory or resources associated with the initial help table. 


The application must allocate space for the help table and fill the table with 
appropriate values before sending this message. The system does not check the 
validity of the help-table contents. 


WinCreateHelpInstance, HM_LOAD_HELP_TABLE 


HM_DISMISS_WINDOW New 


Parameters 


Return Value 


HM_DISMISS_WINDOW 
mpl = OL; /7* not used, must be zero */ 
mp2 = OL; /7* not used, must be zero */ 


An application sends an HM_DISMISS_WINDOW message to a help window to 
close the help window. Closing the help window does not destroy the help 
instance. 


This message does not use any parameters. 


The return value is FALSE if the help window is closed. It is TRUE if the help 
window was already closed. 


Comments A help window is a modeless window. This means the user can view help and 
return to the application window without closing the help window. An applica- 
tion can use the HM_DISMISS_WINDOW message to close the help window if 
the user has not closed it. 

' See Also WinDestroyHelpInstance 
HM_DISPLAY_HELP | New 


HM_DISPLAY_HELP 


mp1 MPFROMP((PVOID) pHelpPanel) ; /* panel ID or pointer to name */ 
mp 2 MPFROMSHORT((USHORT) usTypeFlag) ; /* ID or name flag a/ 


An application sends an HM_DISPLAY_HELP message to a help window to 
display a specific help panel. 


Parameters 


Return Value 


HM_ERROR~ = 197 


pHelpPanel Low and high word of mp1. Points to a help-panel ID, points to a 
null-terminated help-panel name, or contains the help-panel ID in the low word 
and 0x0000 in the high word. 


usTypeFlag Low word of mp2. Specifies whether the pHelpPanel parameter 
specifies a help-panel ID or name. The usTypeFlag parameter can be one of the 
following values: 


Value Meaning 

HM_RESOURCEID Specifies that pHelpPanel points to the help- 
panel ID or contains the help-panel ID in the 
low word. 

HM_PANELNAME Specifies that pHelpPanel points to the null- 


terminated help-panel name. 


The return value is FALSE if the help panel is displayed. Otherwise, it is an 
error value, which may be one of the following: 


HMERR_DATABASE_NOT_OPEN 
HMERR_PANEL_NOT_FOUND 


HMERR_READ_LIB_FILE 

Comments The system searches for the specified panel in the help libraries opened for the 
help window and displays the first matching panel found. 

See Also HM_EXT_HELP, HM_HELP_CONTENTS, HM_HELP_INDEX, 
HM_KEYS_HELP 

HM_ERROR New 
HM_ERROR 
ulErrorCode = (ULONG) LONGEROMMP (mp1) ; /* error type */ 
The HM_ERROR message is sent to notify an application of an error in a help 
window—errors that occur while the user views help. It does not notify the appli- 
cation of errors that result from messages sent by the application. 

Parameters ulErrorCode Low and high word of mp1. Specifies an error value, which may 


be one of the following: 


HMERR_ALLOCATE_SEGMENT 
HMERR_CLOSE_LIB_FILE 
HMERR_CONTENT_NOT_FOUND 
HMERR_DATABASE_NOT_OPEN 
HMERR_FREE_MEMORY 
HMERR_HELP_INSTANCE_UNDEFINE 
HMERR_HELP_INST_CALLED_INVALID 
HMERR_HELPITEM_NOT_FOUND 
HMERR_HELPTABLE_UNDEFINE 
HMERR_INDEX_NOT_FOUND 
HMERR_INVALID_ASSOC_APP_WND 
HMERR_INVALID_ASSOC_HELP_INST 
HMERR_LINVALID_DESTROY_HELP_INST 
HMERR_INVALID_HELPSUBITEM_SIZE 
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HMERR_INVALID_HELP_INSTANCE_HDL 
HMERR_INVALID_LIB_FILE 
HMERR_INVALID_QUERY_APP_WND 
HMERR_NO_FRAME_WND_IN_CHAIN 
HMERR_NO_HELP_INST_IN_CHAIN 
HMERR_NO_MEMORY 
HMERR_OPEN_LIB_FILE 
HMERR_PANEL_NOT_FOUND 
HMERR_READ_LIB_FILE 


Return Value An application should return zero if it processes this message. 


Comments Because a help window does not display error messages to the user, the applica- 
tion should display its own messages when it receives an HM_ERROR message. 


If an error occurs when creating the help instance using the WinCreateHelpIn- 
stance function, the system copies the error value to the ulReturnCode field in 
the HELPINIT structure used with WinCreateHelpInstance. If an error occurs 
for another function or for a message sent to a help window, the return value 
from the function or message sent specifies the error. 


See Also WinCreateHelpInstance 

HM_EXT_HELP New 
HM_EXT_HELP 
mpl = OL; /7* not used, must be zero */ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an HM_EXT_HELP message to a help window to display 
the extended help panel. 


Parameters This message does not use any parameters. 


Return Value The return value is FALSE if the extended help panel is displayed. Otherwise, it 
is an error value, which may be one of the following: 


HMERR_DATABASE_NOT_OPEN 
HMERR_PANEL_NOT_FOUND 
HMERR_READ_LIB_FILE 


Comments For this message to display an extended help panel, the help table for the help 
instance must specify a help-panel ID that corresponds to the active window. 
(For example, the idExtPanel in the HELPTABLE structure used with the Win- 
CreateHelpInstance function must be set to a valid help-panel ID.) If the help 
table specifies zero for the extended help-panel ID, the system sends the 
HM_EXT_HELP_UNDEFINED message to the application. In this case, the 
application should carry out some default action, such as displaying an error 
message or using the HM_DISPLAY_HELP message to display a help panel. 


See Also HM_DISPLAY_HELP, HM_EXT_HELP_UNDEFINED, aa 
HM_KEYS_HELP 
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™ HM_EXT_HELP_UNDEFINED | New 


Parameters 


Return Value 


HM_EXT_HELP_UNDEFINED 


The HM_EXT_HELP_UNDEFINED message notifies the application that an 
extended help panel is not defined for the active window. 


This message does not use any parameters. 


An application should return zero if it processes this message. 


Comments The system displays extended help only if the help table for the help instance 
specifies a help-panel ID that corresponds to the active window. (For example, 
the idExtPanel in the HELPTABLE structure used with the WinCreateHelp- 
Instance function must be set to a valid help-panel ID.) If the help table 
specifies zero for the extended help-panel ID, the system sends the 
HM_EXT_HELP_UNDEFINED message to the application. In this case, the 
application should carry out some default action, such as displaying an error 
message or using the HM_DISPLAY_HELP message to display a help panel. 
See Also HM_DISPLAY_HELP, HM_EXT_HELP 
mM HM_HELP_CONTENTS New 
HM_HELP_CONTENTS 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /7* not used, must be zero */ 
An application sends. an HM_HELP_CONTENTS message to a help window to 
display the table of contents for the open help library. 
Parameters This message does not use any parameters. 
Return Value The return value is FALSE if the table of contents is displayed. Otherwise, it is 
an error value, which may be one of the following: 
HMERR_DATABASE_NOT_OPEN 
HMERR_PANEL_NOT_FOUND 
HMERR_READ_LIB_FILE 
See Also HM_DISPLAY_HELP, HM_HELP_INDEX, HM_KEYS_HELP 
m@ HM_HELP_INDEX New 

HM_HELP_INDEX 

mpl = OL; 7* not used, must be zero */ 

mp2 = OL; 7* not used, must be zero *#/ 


An application sends an HM_HELP_INDEX message to a help window to 
display the index for the open help library. 
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Parameters 


Return Value 


This message does not use any parameters. 


The return value is FALSE if the index is displayed. Otherwise, it is an error 
value, which may be one of the following: 


HMERR_DATABASE_NOT_OPEN 
HMERR_PANEL_NOT_FOUND 
HMERR_READ_LIB_FILE 


See Also HM_DISPLAY_HELP, HM_HELP_CONTENTS, HM_KEYS_HELP 

HM_HELPSUBITEM_NOT_FOUND | New 
HM_HELPSUBITEM_NOT_FOUND 
usMode = (USHORT) SHORT1FROMMP (mp1) ; /* help mode a/ 
idTopic = (USHORT) SHORT1FROMMP (mp2) ; /* window ID for topic */ 
idSubTopic = (USHORT) SHORT2FROMMP (mp2) ; /* window ID for subtopic */ 
The HM_HELPSUBITEM_NOT_FOUND message notifies the application that 
the system failed to find a help panel in response to a user request for help. 

Parameters usMode Low word of mp1. Specifies the context of the help request. This 


Return Value 


Comments 


See Also 


parameter can be one of the following values: 
Value Meaning 


HLPM_FRAME _ The help request is for a focus window that is a child win- 
dow of the client window. 


HLPM_MENU The help request is for a selected menu item or submenu. 


HLPM_WINDOW The help request is for a focus window that is not a child 
window of the client window. 


idTopic Low word of mp2. Specifies the ID of the active frame or dialog win- 
dow or the submenu that contains the selection. 


idSubTopic High word of mp2. Specifies the ID of the window that has the 
keyboard focus or the menu item that contains the selection. 


An application should return FALSE to direct the system to display the 
extended help panel for the active window. An application should return TRUE 
to direct the system to do nothing. 


When an application receives this message, it should carry out a default action, 
such as displaying an error message or using the HM_DISPLAY_HELP message 
to display an explicitly specified help panel, or it can return FALSE to direct the 
system to display the extended help panel. If the application displays an error 
message or a help panel, it must return TRUE to prevent the system from 
displaying the extended help panel. 


HM_DISPLAY_HELP, HM_ERROR 


—@ HM_INFORM 


Parameters 


Return Value 
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New 


HM_INEORM | ; 
i4dPanel = (USHORT) SHORT1FROMMP (mp1) ; /* help-panel ID */ 


The HM_INFORM message notifies an application that the user has chosen a 
hypertext field in the help window. 


idPanel Low word of mp1. Specifies the help-panel ID associated with the 
hypertext field. | 


An application should return zero if it processes this message. 


Comments The system sends an HM_INFORM message only if the corresponding hypertext 
field was created using the :inform tag. The value of the idPanel parameter is the 
number specified with the tag. This is usually a help-panel ID, but it can be any 
number. When an application receives the HM_INFORM message, it can carry 
out any action; however, after the application returns from the message, the sys- 
tem displays the corresponding help panel if one exists. 

See Also HM_DISPLAY_HELP 

mM HM_KEYS_HELP New 
HM_KEYS_HELP 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 
An application sends an HM_KEYS_HELP message to a help window to display 
the help panel that contains information about the application keys. 

Parameters This message does not use any parameters. 


Return Value 


Comments 


See Also 


The return value is FALSE if the keys-help panel is displayed. Otherwise, it is 


an error value, which may be one of the following: 


HMERR_DATABASE_NOT_OPEN 
HMERR_PANEL_NOT_FOUND 
HMERR_READ_LIB_FILE 


Because the keys-help-panel ID is not specified in the help table, the system 
sends an HM_QUERY_KEYS_HELP message to the window associated with 
the help window or to the active window. If the application returns the keys- 
help-panel ID, the system displays the keys-help window. 


HM_DISPLAY_HELP, HM_EXT_HELP, HM_HELP_CONTENTS, 
HM_HELP_INDEX 
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HM_LOAD_HELP_TABLE New 
HM_LOAD_HELP_TABLE 
mp1 = MPEROM2SHORT(OxFFFF, (USHORT) idHelpTable); /* help-table ID av, 


Parameters 


Return Value 


mp 2 MPFROMSHORT ( (USHORT) hmodModule) ; /* module with resource a/ 


An application sends an HM_LOAD_HELP_TABLE message to a help window 
to replace the existing help table (if any) with a help-table resource. 


idHelpTable Low word of mp1. Specifies the resource ID of the help-table 
resource. 


hmodModule Low word of mp2. Identifies the module that contains the 
help-table resource. 


The return value is FALSE. 


Comments Applications can use this message to replace the initial help table of a help 
instance or to set the table if no initial help table is given. The initial help table 
is specified in the HELPINIT structure used when the help instance is created by 
using the WinCreateHelpInstance function. This message replaces the help table 
without freeing any memory or resources associated with the initial help table. 

See Also WinCreateHelpInstance, HM_CREATE_HELP_TABLE 

HM_QUERY_KEYS_HELP New 
HM_QUERY_KEYS_HELP 
mpl = OL; 7* not used, must be zero */ 
mp2 = OL; /7* not used, must be zero */ 

The HM_QUERY_KEYS_HELP message is sent to an application to retrieve 
the keys-help-panel ID. 
Parameters This message does not use any parameters. 


Return Value 


An application should return the keys-help-panel ID. If no keys-help panel 
exists, the application should return an alternate panel ID, such as the ID for 
extended help. 


Comments The system uses the returned ID to display the corresponding help panel. If the 
return value is not a valid help-panel ID, no help is displayed. 
See Also HM_KEYS_HELP 
HM_REPLACE_HELP_FOR_HELP | New 
_ HM_REPLACE_HELP_FOR_HELP 
mpl = MPFROMSHORT (idHelpForHelpPanel) ; /* help-panel ID a/ 
mp2 = OL; /* not used, must be zero */ 


An application sends an HM_REPLACE_HELP_FOR_HELP message to a help 
window to replace the general help panel (supplied by the system) with a 
specified help panel. 


Parameters 
Return Value 


Comments 


See Also 
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idHelpForHelpPanel Low word of mp1. Specifies a help-panel ID. 
The return value is zero. 


A help window displays the general help panel whenever an application specifies 
zero for the help-panel ID in an HM_DISPLAY_HELP message. The general 
help panel is initially set by the system when the help instance is created; appli- 
cations can replace the system-supplied help at any time. Applications that 
modify the help-window menu should also replace the general help information. 


HM_DISPLAY_HELP 


HM_SET_ACTIVE_WINDOW New 


Parameters 


Return Value 


See Also 


HM_SET_ACTIVE_WINDOW 
mpl = MPFROMHWND (hwndActiveWindow) ; /* active-window handle a/ 
mp2 = MPFROMHWND (hwndRelativeWindow) ; /* application-window handle */ 


An application sends an HM_SET_ACTIVE_WINDOW message to a help win- 
dow to set the active and relative windows. The active window is the window to 
which the system sends help messages. The relative window is the window next 

to which the system displays the help window. 


hwndActiveWindow _ Low and high word of mp1. Identifies the active window. 
This value can be a window handle or NULL. If this parameter is NULL, the 
active and relative windows are determined by the system. 


hwndRelativeWindow Low and high word of mp2. Identifies the relative win- 
dow. This value can be a window handle or HWND_PARENT. If the value is 
HWND_PARENT, the system sets the relative window to be the parent window 
of the active window. 


The return value is FALSE. 


WinAssociateHelpInstance 


HM_SET_HELP_LIBRARY_NAME New 


Parameters 


Comments 


HM_SET_HELP_LIBRARY_NAME 


mpi 
mp2 


MPFROMP (pszHelpLibraryName); /* pointer to help-library name */ 
OL; /7* not used, must be zero a/ 


An application sends an HM_SET_HELP_LIBRARY_NAME message to Help 
Manager to identify the help library to search. 


pszHelpLibraryName Low word of mp1. Points to the string that contains the 
help-library name used by Help Manager when it searches for the requested help 
topic. 


Sending an HM_SET_HELP_LIBRARY_NAME message replaces the current 
help library with the library specified. 
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HM_SET_HELP_WINDOW_TITLE New 


Parameters 


Return Value 


Comments 


See Also 


HM_SET_HELP_WINDOW_TITLE 
mpl = MPFROMP (pszHelpWindowTitle) ; /* pointer to new title */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an HM_SET_HELP_WINDOW_LTITLE message to a help 
window to change the window title. 


pszHelpWindowTitle Low and high word of mp1. Points to the null- 
terminated string that contains the new Help-window title. 


The return value is FALSE if the window title is set. Otherwise, it is an error 
value, which may be one of the following: 


HMERR_ALLOCATE_SEGMENT 
HMERR_NO_MEMORY 


The initial window title is specified by setting the pszHelpWindowTitle field in 
the HELPINIT structure used when the help instance is created by using the 
WinCreateHelpInstance function. The system allocates memory to save the title 
and frees the memory when the HM_SET_HELP_WINDOW_LTITLE message is 
used to change the title. 


WinCreateHelpInstance 


HM_SET_SHOW_PANEL_ID _ New 


Parameters 


Return Value 


Comments 


See Also 


HM_SET_SHOW_PANEL_ID 
mpl = MPFROMSHORT (fVisible) ; /* help-panel ID flag */ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an HM_SET_SHOW_PANEL_ID message to a help win- 
dow to specify whether the window should display the help-panel ID along with 
the help panel title. 


fVisible Low word of mp1. Specifies whether to display or hide the help-panel 
ID. This parameter can be one of the following values: 


Value Meaning 

CMIC_HIDE_PANEL_ID Turns off the show option. The help-panel ID 
is not displayed. 

CMIC_SHOW_PANEL_ID Turns on the show option. The help-panel ID 
is displayed. 

CMIC_TOGGLE_PANEL_ID Toggles the display of the help-panel ID. 


The return value is zero. 
The help window displays the help-panel ID along with the help-panel title in the 
title bar of the help-panel window. The panel ID is enclosed in brackets. 


Initially, an application specifies whether to display the help-panel ID by setting 
the usShowPanelld field in the HELPINIT structure when the help instance is 
created by using the WinCreateHelpInstance function. 


WinCreateHelpInstance 
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mM HM_TUTORIAL New 


HM_TUTORIAL 
pszTutorialName = (PSZ) PVOIDFROMMP (mp1) ; /* pointer to tutorial */ 


The HM_TUTORIAL message is sent to a window when the user chooses the 
Tutorial command in the help window menu. The application can then invoke its 
own tutorial program. 


Parameters pszTutorialName Low and high word of mp1. Points to the null-terminated 
tutorial name. 

Return Value An application should return zero if it processes this message. 

Comments An application sets the name of the tutorial by setting the pszTutorialName field 


in the HELPINIT structure used when the help instance is created by using the 
WinCreateHelpInstance function. If a tutorial name is specified, the help win- 
dow adds the Tutorial command to its Help menu. 


See Also WinCreateHelpInstance 


™@ KbdCharin Change 


USHORT KbdCharin( pkbci, fWait, hkbd) 

PKBDKEYINFO pkbci; /« pointer to structure for keystroke info. »/ 
USHORT fWait; /» wait/no-wait flag »/ 
HKBD hkbd; /« keyboard handle »/ 


The KbdCharIn function retrieves character and scan-code information from a 
logical keyboard. The function copies the information to a specified structure. 
Keystroke information includes the character value of a given key, the scan 
code, the keystroke status, the state of the shift keys, and the system time (in 
milliseconds) when the keystroke occurred. 


The KbdCharIn function is a family API function. 


Parameters pkbci_ Points to the KBDKEYINFO structure that receives the keystroke infor- 


mation. The KBDKEYINFO structure has the following form: 
typedef struct _KBDKEYINFO { 

UCHAR chChar; 

UCHAR chScan; 

UCHAR fbStatus; 

UCHAR bNlsShift; 

USHORT fsState; 

ULONG time; 
} KBDKEYINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


fWait Specifies whether to wait for keystroke information if none is available. 
If this parameter is IO_WAIT, the function waits for a keystroke if one is not 
available. If this parameter is IO_LNOWAIT, the function returns immediately 
whether or not it retrieved any keystroke information. The fbStatus field in the 
KBDKEYINFO structure specifies whether a keystroke is received. The fbStatus 
field is nonzero if a keystroke is received or zero if not. 
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Return Value 


Comments 


Restrictions 


Example 


See Also 


hkbd Identifies the logical keyboard. The handle must have been created by 
using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_INVALID_IOWAIT 
ERROR_KBD_INVALID_HANDLE 


The KbdCharIn function copies and removes keystroke information from the 
input buffer of the specified logical keyboard. Although echo mode for the logi- 
cal keyboard may be turned on, KbdCharIn does not echo the characters it 
reads. If the keyboard is in ASCII mode, KbdCharIn retrieves keystroke infor- 
mation for each key pressed except shift keys. If the keyboard is in binary mode, 
KbdCharIn retrieves keystroke information for any key pressed except shift 
keys. In most cases, a shift key is pressed in combination with other keys to 
create a single keystroke. In binary mode with shift reporting turned on, a shift 
key by itself creates a keystroke this function can retrieve. For more information 
on binary mode and shift-reporting mode, see the KbdSetStatus function. 


The KbdCharIn function retrieves extended ASCII codes, such as when the ALT 
key and another key, called the primary key, are pressed simultaneously. When © 
the function retrieves an extended code, it sets the chChar field of the 
KBDKEYINFO structure to 0x0000 or Ox00E0. It also sets the fbStatus field to 
EXTENDED_CODE and copies the extended code to the chScan field. Note 
that both fields need to be examined to determine whether an extended code has 
been received. The extended code is usually the scan code of the primary key. In 
ASCII mode, the function retrieves only complete extended codes, which means 
that if both bytes of the extended code do not fit in the buffer, neither byte is 
retrieved. For more information, see the Microsoft Operating System/2 
Programmer’s Reference, Volume 3. 


This function must be called twice to retrieve a code for a double-byte character 
set (DBCS). If the code retrieved is the first byte of a double-byte character, the 
fbStatus field of the KBDKEYINFO structure is set to 0x0080. 


In real mode, the following restrictions apply to the KbdCharIn function: 

m™ It does not copy the system time to the KBDKEYINFO structure and 
there is no interim character support. 

m™ It retrieves characters only from the default logical keyboard (handle 0). 

m The fbStatus field can be 0x0000 or SHIFT_KEY_IN. 

m The hkbd parameter is ignored. 


This example calls the KbdCharIn function to retrieve a character, and then 
displays the character on the screen: 


KBDKEYINFO kbci; 
KbdCharIn (&kbei, /7* structure for data */ 
IO_WAIT, ; /* waits for key 
0); /* keyboard handle */ 
VioWrtTTY (&kbci.chChar, 1, 0); 


KbdGetStatus, KbdOpen, KbdPeek, KbdSetStatus, KbdStringIn 
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Changes In order to allow for input OxOOEO as a normal character, a new value has been 
added to the fbStatus field of the KBDKEYINFO structure. In order to detect an 
extended code, both of the following conditions must be true: 


™@ chChar must be equal to 0x0000 or 0x00E0 
@ fbStatus must be equal to EXTENDED_CHAR 


KbdGetHWID New 


USHORT KbdGetHWID( pkbdhwid, hkbd) 
PKBDHWID pkbdhwid; /« pointer to structure for ID number «/ 
HKBD hkbda; /« keyboard handle »/ 


The KbdGetHWID function retrieves the hardware ID number of a keyboard. 


Parameters pkbdhwid Points to the KBDHWID structure that receives the ID number of 
the keyboard. The KBDHWID structure has the following form: 
typedef struct _KBDHWID { 
USHORT cb; 
USHORT idKbd; 
USHORT usReservedl1; 


USHORT usReserved2; 
} KBDHWID; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hkbd Identifies the logical keyboard. This handle must have been created by 
using the KbdOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_DETACHED 
ERROR_KBD_INVALID_HANDLE 


ERROR_KBD_PARAMETER 
Example This example opens a logical keyboard, and then calls the KbdGetHWID func- 
tion to retrieve the hardware ID number of that keyboard: 
HKBD hkbd; 
KBDHWID kbhw; 
KbdOpen (&hkbd) ; /* opens keyboard */ 
KbdGetFocus (IO_WAIT, hkbda) ; /* gets focus for keyboard */ 
kbhw.cb = sizeof (kbhw) ; /* sets structure length 4 
x 


KbdGetHWID (&kbhw, hkbd) ; /* gets ID number 


See Also DosDevIOCtl, KbdOpen 
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mM KbdRegister 


Change 


USHORT KbdRegister( pszModuleName, pszEntryName, fFunctions) 


PSZ pszModuleName; /« pointer to string for module name »/ 


PSZ pszEntryName; 


ULONG fFunctions; 


Parameters 


Return Value 


/« pointer to string for entry-point name +/ 
/« function flags s/ 


The KbdRegister function registers a Kbd subsystem for the specified logical 
keyboard. The function temporarily replaces the specified default Kbd functions 
with the functions in the specified module. Once KbdRegister replaces a func- 
tion, MS OS/2 passes any subsequent call to the replaced function to a function 
in the given module. If a function is not replaced, MS OS/2 continues to call the 
default Kbd function. 


pszModuleName Points to the null-terminated string that contains the name 
of the dynamic-link module that specifies the replacement Kbd functions. The 
string must be a valid filename. 


pszEntryName Points to the null-terminated string that contains the name of 
the dynamic-link entry-point function. For a full description, see the following 
“Comments” section. 


fFunctions Specifies the flags for the functions to be replaced. This parameter 
can be any combination of the following values: 


Value Meaning 
KR_KBDCHARIN Replace KbdCharlIn. 
KR_KBDPEEK Replace KbdPeek. 
KR_KBDFLUSHBUFFER Replace KbdFlushBuffer. 
KR_KBDGETSTATUS Replace KbdGetStatus. 
KR_KBDSETSTATUS Replace KbdSetStatus. 
KR_KBDSTRINGIN Replace KbdStringIn. 
KR_KBDOPEN Replace KbdOpen. 
KR_KBDCLOSE Replace KbdClose. 
KR_KBDGETFOCUS Replace KbdGetFocus. 
KR_KBDFREEFOCUS Replace KbdFreeFocus. 
KR_KBDGETCP Replace KbdGetCp. 
KR_KBDSETCP Replace KbdSetCp. 
KR_KBDXLATE Replace KbdXlate. 
KR_KBDSETCUSTXT Replace KbdSetCustXt. 
KR_KBDGETHWID © Replace KbdHWId. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_INVALID_ASCIIZ 
ERROR_KBD_INVALID_MASK 
ERROR_KBD_REGISTER 
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Comments MS OS/2 passes a Kbd function to the given module by preparing the stack and 
calling the function pointed to by the pszEntryName parameter. The specified 
module must export the entry-point function name. The entry-point function 
must check the function code on the stack to determine which function is being 
requested and then pass control to the appropriate function in the module. The 
entry-point function can then access any additional parameters placed on the 
stack by the original call to KbdRegister. 


Only one process in a screen group can use the KbdRegister function at any 
given time. That is, only one process can replace Kbd functions at any given 
time. The process can restore the default Kbd functions by calling the Kbd- 
DeRegister function. A process can replace Kbd functions any number of times, 
but only by first restoring the default functions and then reregistering the new 
functions. 


The entry-point function (FuncName) must have the following form: 


SHORT FAR FuncName(selDataSeg, usReserved1, fFunction, 
ulReserved2, usParaml, usParam2, usParam3, usParam4, 
usParamS, usParam6) 

SEL selDataSeg; 

USHORT usReserved]; 

USHORT fFunction; 

ULONG ulReserved2; 

USHORT usParamd; 

USHORT usParam2; 

USHORT usParam3; 

USHORT usParam4; 

USHORT usParam5; 

USHORT usParam6; 


Parameters Description 
selDataSeg Specifies the data-segment selector of the process that 
calls the specified Kbd function. 


usReserved1 Specifies a reserved value that must not be changed. 
This value represents a return address for the MS 
OS/2 function that routes Kbd function calls. 


fFunction Specifies the function code of the function request. 
This parameter can be one of the following values: 


Value , Meaning 

0x0000 KbdCharIn called. 
0x0001 KbdPeek called. 
0x0002 KbdFlushBuffer called. 
0x0003 KbdGetStatus called. 
0x0004 KbdSetStatus called. 
0x0005 KbdStringIn called. 
0x0006 KbdOpen called. 
0x0007 KbdClose called. 
0x0008 KbdGetFocus called. 


0x0009 KbdFreeF ocus called. 
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Return Value 


Value Meaning 
Ox000A. KbdGetCp called. 
0x000B KbdSetCp called. 
0x000C KbdXlate called. 
0x000D KbdSetCustXt called. 
0x000E KbdGetHWId called. 
ulReserved2 Specifies a reserved value that must not be changed. 


This value represents the return address of the pro- 
gram that calls the specified Kbd function. 


usParam1-usParam6 Specify up to six unsigned values passed with the call 
to the Kbd function. The number and type of parame- 
ters used depend on the specific function. 


The entry-point function should determine which function is requested and then 
carry out an appropriate action by using the passed parameters. If necessary, the 
entry-point function can call a function within the same module to carry out the 
task. The entry-point or replacement function must leave the stack in the same 
state as it was received because the return addresses on the stack must be avail- 
able in the correct order to return control to the program that originally called 
the KbdRegister function. 


The registered function should return - 1 to call the original function, 0 if no 
error occurred, or an error value. 


In general, to access the keyboard the replacement function must use the input- 
and-output control functions for the keyboard. 


The KbdRegister function itself cannot be replaced. 


See Also KbdDeRegister, KbdFlushBuffer 

Changes The KR_KBDGETTHWID constant for the new function KbdGetHWId has 
been added to the functions list and also to the return list. 

MLM_CHARFROMLINE New 
MLM_CHARFROMLINE 
mpl = MPFROMLONG( (LINE) 1LineNum) ; /* line number */ 
mp2 = OL; /* not used, must be zero */ 
An application sends an MLM_CHARFROMLINE message to obtain the offset 
(number of characters from the beginning of the text) of the first character on 
the specified line in a multiple-line entry field (MLE). 

Parameters ILineNum Low and high word of mp1. Specifies the line number. A value of 


zero specifies the first line. A value of - 1 specifies the line that contains the cur- 
sor. 


The return value is the 32-bit offset of the first character on the specified line. 


Comments 


See Also 


MLM_CLEAR 


Parameters 


Return Value 


See Also 


MLM_COPY 
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If the /LineNum parameter specifies a line number greater than the line number 
of the last line of text in the MLE, the insertion point returned will be the point 
to the right of the last character in the MLE. 


A line consists of all text up to a carriage return. A line may be displayed as 
several lines on the screen due to word-wrapping and still be considered a single 
line when specifying the line number for the /LineNum parameter. 


Line numbers are zero-based. Therefore, the first line in an MLE is zero. 


MLM_LINEFROMCHAR 


New 
MLM_CLEAR : 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_CLEAR message to clear (delete) selected text 
in a multiple-line entry field (MLE). 


This message does not use any parameters. 


The return value is a 32-bit value (ULONG) that specifies the number of charac- 
ters deleted. 


MLM_CUT, MLM_DELETE 


New 


Parameters 


Return Value 


Comments 


See Also 


MLM_COPY 
mp1 = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_COPY message to copy selected multiple-line 
entry field (MLE) text to the clipboard. 


This message does not use any parameters. 


The return value is a 32-bit value (ULONG) that specifies the number of charac- 
ters copied to the clipboard. 


If no text is selected, the previous contents of the clipboard remain unaltered. 


MLM_CUT, MLM_PASTE 
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@ MLM_CUT . New 
MLM_CUT 
mp1 = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_CUT message to copy selected multiple-line 
entry-field (MLE) text to the clipboard and then clear the selected text. — 


Parameters This message does not use any parameters. 


Return Value The return value is a 32-bit value (ULONG) that specifies the number of charac- 
ters copied and cleared. 


Comments If no text is selected, the previous contents of the clipboard remain unaltered. 
See Also MLM_COPY, MLM_DELETE, MLM_PASTE 
mM MLM_DELETE New 
MLM_DELETE | 
mpl = MPFROMLONG((LINE) 1Begin) ; /* beginning of deletion */ 
mp2 = MPFROMLONG((ULONG) cch); /* characters to delete */ 


An application sends an MLM_DELETE message to delete the specified number 
of characters from a multiple-line entry field (MLE). 


Parameters [Begin Low and high word of mp1. Specifies the offset (number of characters 
from the beginning of the text) of the first character to delete. If this parameter 
is set to -1, the current selection (if any) is deleted. 


cch_ Low and high word of mp2. Specifies the number of characters to delete. 
This parameter is ignored if the /Begin parameter is set to - 1. 


Return Value The return value is a 32-bit value (LONG) that specifies the number of charac- 
ters deleted. 


See Also MLM_CUT _ 
m™ MLM_DISABLEREFRESH | New 
MLM_DISABLEREFRESH 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_DISABLEREFRESH message to Prevent: 
repainting (refresh) of a multiple-line entry field (MLE). 


Parameters This message does not use any parameters. 
Return Value The return value is always TRUE. 


Comments When refresh is disabled, the MLE does not accept any keyboard or mouse 
input. If the mouse is moved over the MLE, it becomes an hourglass pointer. 


See Also MLM_ENABLEREFRESH 
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mM MLM_ENABLEREFRESH New 
MLM_ENABLEREFRESH 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; 7* not used, must be zero */ 


Parameters 
Return Value 


See Also 


mM MLM_EXPORT 


Parameters 


Return Value 


Comments 


See Also 


An application sends an MLM_ENABLEREFRESH message to enable repaint- 
ing (refresh) of a multiple-line entry field (MLE). While the refresh state is 
enabled, the entire MLE window is repainted. 


This message does not use any parameters. 


The return value is always TRUE. 


MLM_DISABLEREFRESH 
New 
MLM_EXPORT 
mpl = MPFROMP((PIPT) plOffset) ; /* beginning of copy area Py 
mp2 = MPFROMP((PULONG) pcbCopy); /* bytes to copy 


An application sends an MLM_EXPORT message to export text from a 
multiple-line entry field (MLE) by copying the specified number of characters 
from the MLE to the buffer specified by the MLM_SETIMPORTEXPORT mes- 
sage. If all of the specified characters are on a single line, only the specified 
characters are copied. If the specified characters are on more than one line, the 
entire line containing the last specified character is copied. 


plOffset Low and high word of mp1. Points to the variable that specifies the 
offset (number of characters from the beginning of the text) of the first character 
to copy. A value of - 1 specifies the current cursor position. On return, this vari- 
able contains the offset to the first character not copied to the buffer. 


pcebCopy Low and high word of mp2. Points to the variable that specifies the 
number of characters to copy. On return, this variable is zero if the number of 
characters actually copied does not exceed the numbers specified to be copied. 
It is nonzero if the number of characters specified includes a line break and a 
portion of another line. 


The return value is a 32-bit value (ULONG) that specifies the number of bytes 
actually copied. This value includes carriage-return and linefeed characters 
copied to the buffer. 


The text is copied in the form set by the MLM_FORMAT message. Note that 
the buffer is not zero-terminated. 


All exports are done in full characters. Therefore, if the length of the buffer or 
the number of bytes to be exported results in the last byte transferred being only 
half of a double-byte character set (DBCS) character, the MLE does not 
transfer that byte. 


MLM_FORMAT, MLM_SETIMPORTEXPORT 
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mM MLM_FORMAT 


Parameters 


See Also 


—@ MLM_IMPORT 


New 
MLM_FORMAT 
mp1 = MPFROMSHORT(usFormat); /* format to set a/ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an MLM_FORMAT message to set the format for import- 
ing to or exporting from a multiple-line entry field (MLE). . 


usFormat Low word of mp1. Specifies the format to set. This parameter can 
be one of the following values: 


Value Meaning 


MLFIE_CFTEXT Specifies the clipboard text format. This 
format uses carriage-return/linefeed char- 
acters for line breaks on export, and 
recognizes linefeed, carriage-return/ 
linefeed, or linefeed/carriage-return char- 
acters for line breaks on import. This is 
the default format. 


MLFIE_NOTRANS Specifies a format that uses linefeed char- 
acters for line breaks. This value guaran- 
tees that any text imported into the MLE 
in this form can be recovered in exactly 

' the same form on export. 


MLFIE_WINFMT Specifies the format of the MLE window. 
This format recognizes carriage-return/ 
linefeed characters for line breaks on 
import. It ignores the sequence carriage- 

_ return/carriage-return/linefeed. On export, 
it uses carriage-return/linefeed characters 
to denote a hard line break and carriage- 
return/carriage-return/linefeed characters 
to denote a soft line break caused by 
word-wrapping. 


MLM_EXPORT, MLM_IMPORT, MLM_QUERYFORMATLINELENGTH, 
MLM_QUERYFORMATTEXTLENGTH 


New 


Parameters 


MLM_IMPORT : 
mpl = MPFROMP (plOffset) ; /* import offset a/ 
mp2 = MPFROMLONG(cbCopy) ; /* number of bytes to copy */ 


An application sends an MLM_IMPORT message to insert the contents of the 
buffer specified by the MLM_SETIMPORTEXPORT message into the multiple- 
line entry field (MLE). 


plOffset Low and high word of mp1. Points to the variable that specifies the 
offset (number of characters from the beginning of the text) to the edit-control 
buffer where the import buffer is to be inserted. A value of - 1 specifies the 
current cursor position. On return, this variable contains the offset to the first 
character beyond the imported buffer. 


Return Value 


Comments 


See Also 


MLM_INSERT 


Parameters 


Return Value 


MLM_LINEFROMCHAR- = 215 


cbCopy Low and high word of mp2. Specifies the number of bytes to import. 
If the last byte transferred is half of a double-byte character or part of a line- 
break sequence (carriage-return/linefeed), the last character is not transferred. 


The return value is a 32-bit value (ULONG) that specifies the number of bytes 
actually imported. This may be less than the value specified by the cbCopy 
parameter—if the last byte to copy included only part of a double-byte character 
or part of a line-break sequence. The return value is zero if the import would 
overflow the text limit set by the MLM_SETTEXTLIMIT message. 


The contents of the buffer are interpreted as being in the form set by the 
MLM_FORMAT message. 


MLM_FORMAT, MLM_SETIMPORTEXPORT, MLM_SETTEXTLIMIT, 
MLN_OVERFLOW, WM_CONTROL 


New 
MLM_INSERT 
mpl = MPFROMP (pszBuf) ; /* pointer to text */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_INSERT message to insert text into a multiple- 
line entry field (MLE) at the current cursor position. 


pszBuf Low and high word of mp1. Points to the null-terminated string that 
contains the text to insert. 


The return value is TRUE if the text is inserted successfully or FALSE if an 
error occurs. If the inserted text overflows a text limit or format rectangle, an 
error occurs and an appropriate notification message is sent. 


See Also MLN_OVERFLOW, MLN_TEXTOVERFLOW, WM_CONTROL 
MLM_LINEFROMCHAR New 
MLM_LINEFROMCHAR 
mpl = MPFROMLONG(10f fset) ; /* offset of MLE character */ 
mp2 = OL; /* not used, must be zero */ | 
An application sends an MLM_LINEFROMCHAR message to obtain the 
number of the line that contains the specified character in a multiple-line entry 
field (MLE). 
Parameters lOffset Low and high word of mp1. Specifies the offset (number of characters 


Return Value 


from the beginning of the text) of the specified character. A value of - 1 
specifies that the number of the line that contains the cursor is returned. If the 
offset specified is greater than the total number of characters currently in the 
MLE, the number of the last line is returned. 


The return value is a 32-bit value (ULONG) that specifies the number of the line 


that contains the specified character. 
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Comments Line numbers are zero-based. Therefore, the first line in an MLE is zero. 

See Also MLM_CHARFROMLINE 

MLM_PASTE New 
MLM_PASTE 
mpl = OL; /7* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_PASTE message to copy the contents of the clip- 
board to a multiple-line entry field (MLE). 


Parameters This message does not use any parameters. 


Return Value The return value is a 32-bit value (ULONG) that specifies the number of charac- 
ters copied. If the clipboard contains an incompatible format, the return value is 


zero. 

See Also MLM_COPY, MLM_CUT 

MLM_QUERYBACKCOLOR New 
MLM_QUERYBACKCOLOR 
mpl = OL; 7* not used, must be O */ 


mp2 = OL; /* not used, must be O */ 


An application sends an MLM_QUERYBACKCOLOR message to obtain 
background-color information for a multiple-line entry field (MLE). 


Parameters This message does not use any parameters. 


‘Return Value The return value is a 32-bit value (COLOR) that specifies the background color. 
. It can be one of the following values: 


Value Meaning 
CLR_FALSE All color planes are zeros. 
CLR_TRUE All color planes are ones. 
CLR_DEFAULT Default value; same as CLR_NEUTRAL. 
CLR_WHITE White. 
CLR_BLACK Black. 
CLR_BACKGROUND Reset color. 

_ CLR_BLUE Blue. 
CLR_RED Red. 
CLR_PINK Pink. 
CLR GREEN Green. 
CLR_CYAN Cyan. 


CLR_YELLOW Yellow. 
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Value Meaning 
CLR_NEUTRAL Neutral. 
CLR_DARKGRAY Dark gray. 
CLR_DARKBLUE Dark blue. 
CLR_DARKRED . Dark red. 
CLR_DARKPINK Dark pink. 
CLR_DARKGREEN Dark green. 
CLR_DARKCYAN Dark cyan. 
CLR_BROWN Brown. 
CLR_PALEGRAY Light gray. 
See Also MLM_QUERYTEXTCOLOR, MLM_SETBACKCOLOR 
MLM_QUERYCHANGED New 
MLM_QUERYCHANGED 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 
An application sends an MLM_QUERYCHANGED message to determine if the 
text in a multiple-line entry field (MLE) has changed since the last time the 
changed flag was cleared. 
Parameters This message does not use any parameters. 


Return Value 
Comments 


See Also. 


The return value is TRUE if the text has changed since the last time the changed 
flag was cleared. It is FALSE if the text is unchanged or if an error occurs. 


The changed flag can also be set or cleared by using an MLM_SETCHANGED 
message. 


MLM_SETCHANGED, MLN_CHANGE, WM_CONTROL 


MLM_QUERYFIRSTCHAR | New 


Parameters 


Return Value 


See Also 


MLM_QUERYFIRSTCHAR 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYFIRSTCHAR message to retrieve the 
offset (number of characters from the beginning of the text) of the first visible 
character in a multiple-line entry field (MLE). 


This message does not use any parameters. 


The return value is a 32-bit value (ULONG) that specifies the offset of the first 
visible character. 


MLM_SETFIRSTCHAR 
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MLM_QUERYFONT New 


Parameters 


Return Value 


Return Value 


Comments 


MLM_QUERYFONT 
mpl = MPFROMP (pfattrs) ; /* pointer to structure with font info. */ 
mp2 = OL; /* not used, must be zero * 


An application sends an MLM_QUERYFONT message to retrieve font informa- 
tion for a multiple-line entry field (MLE). 


pfattrs Low and high word of mp1. Points to the FATTRS structure that con- 
tains font information. The FATTRS structure has the following form: 


typedef struct _FATIRS { 
USHORT usRecordLength; 
USHORT fsSelection; 
LONG 1Match; 
CHAR szFacename [FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG 1MaxBaselineExt; 
LONG lAveCharWidth; 
USHORT fsType; 
USHORT fsFontUse; 

} FATTRS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


The return value is TRUE if the system font is in use; otherwise, it is FALSE. 


See Also MLM_SETFONT 

MLM_QUERYFORMATLINELENGTH New 
MLM_QUERYF ORMATLINELENGTH 
mpl = MPFROMLONG((LONG) 10ffset); /* offset of beginning character me 
mp2 = OL; 7* not used, must be zero */ 
An application sends an MLM_QUERYFORMATLINELENGTH message to 
retrieve the length (in bytes) of a line in a multiple-line entry field (MLE). 

Parameters lOffset Low and high word of mp1. Specifies the offset (number of characters 


from the beginning of the text) of the first character to count. If this value is - 1, 
the current cursor position is used as the starting character. 


The return value is a 32-bit value (ULONG) that specifies the number of bytes 


between the specified character and the beginning of the next line. If the 


specified character is on the last line in the MLE, the number of bytes to the 
end of that line is returned. 


The number of bytes returned for the end-of-line character is determined by the 
format specified by the MLM_FORMAT aoe This format can be one of 
the following values: 


Format Description 
MLFIE_CFTEXT The end-of-line character is formatted as carriage- 
return/linefeed characters (2 bytes). 


MLFIE_NOTRANS The end-of-line character is formatted as a linefeed 
character (1 byte). 


See Also 


MLM_QUERYFORMATRECT 


Format Description 


MLFIE_WINFMT The end-of-line character for hard line breaks is 
formatted as carriage-return/linefeed characters 
(2 bytes). The end-of-line character for soft line 
breaks (line breaks caused by word-wrapping) is 
formatted as carriage-return/carriage-return/ 
linefeed characters (3 bytes). 


MLM_FORMAT, MLM_QUERYFORMATTEXTLENGTH, 


MLM_QUERYLINELENGTH 


El MLM_QUERYFORMATRECT 


Parameters 


MLM_QUERYFORMATRECT 


mp1 = MPEROMP((PMLEFORMATRECT) pmlefrmrcl); 


New 


mp2 = MPFROMP((PULONG) pflOptions) ; /* point to variable 


An application sends an MLM_QUERYFORMATRECT message to retrieve the 


dimensions used to define the format rectangle for a multiple-line entry field 


(MLE). 


pmlefrmrcl Low and high word of mp1. Points to the MLEFORMATRECT 
structure that receives the format-rectangle dimensions for the MLE. The 
MLEFORMATRECT structure has the following form: 


typedef struct _MLEFORMATRECT { 
LONG cxFormat; 
LONG cyFormat; 

} MLEFORMATRECT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


/* point to MLEFORMATRECT +*/ 
*/ 


pflOptions Low and high word of mp2. Points to the variable that receives the 
flags that specify how the format rectangle is to be used. A value of zero causes 
the MLE to remove any format rectangle and to ignore the pmlefrmrcl parame- 
ter. Otherwise, this parameter can be a combination of the following values: 


Value 


MLFFMTRECT_LIMITHORZ 


Meaning 


Specifies that the text within the MLE 
cannot exceed the horizontal dimension 
specified by the pmlefrmrcl parameter. If 
word-wrap mode is turned on before the 
format rectangle is set, lines automatically 
wrap to stay within the horizontal limit of 
the format rectangle. If word-wrap mode is 
turned off before the format rectangle is ~ 
set, an MLN_PIXHORZOVERFLOW 
notification message is sent to the applica- 
tion whenever an operation would exceed 
the horizontal limit specified in the format. 
rectangle. 
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Return Value 


Comments 


Value Meaning 


MLFFMTRECT_LIMITVERT Specifies that the text within the MLE 
cannot exceed the vertical dimension 
specified by the pmlefrmrcl parameter. An 
MLN_PIXVERTOVERFLOW notification 
message is sent to the application when- 
ever an MLE operation would cause text 
to exceed the vertical limit. 


MLFFMTRECT_MATCHWINDOW Specifies that the format rectangle is to be 
kept the same size as the MLE window 
(minus the border or scroll bars). 


MLFFMTRECT_FORMATRECT _ Specifies that the format rectangle is to be 
kept the same size as the MLE window 

(minus the border or scroll bars) and that 
text cannot exceed the size of the window. 
This value is equivalent to combining 
the MLFFMTRECT_LIMITHORZ, 
MLFFMTRECT_LIMITVERT, and 
MLFFMTRECT_MATCHWINDOW 


values. 

Return Value The return value is always FALSE. 

See Also MLM_SETFORMATRECT 

MLM_QUERYFORMATTEXTLENGTH New 
MLM_QUERYFORMATTEXTLENGTH 
mpl = MPFROMLONG((LONG) l10ffset); /* offset of starting character */ 
mp2 = MPFROMLONG( (LONG) cbChar) ; i fo characters to scan */ 
An application sends an MLM_QUERYFORMATTEXTLENGTH message to 
retrieve the length (in bytes) of a range of characters in multiple-line entry field 
(MLE). 

Parameters lOffset Low and high word of mp1. Specifies the offset (number of characters 


from the beginning of the text) of the first character to count. If this parameter 
is set to - 1, the current cursor position is used as the starting character. 


cbChar Low and high word of mp2. Specifies the number of characters to 
scan. If this parameter is set to -1, the entire text is scanned. 


The return value is a 32-bit value (ULONG) that specifies the number of bytes in 
the specified range of characters. 


The number of bytes returned for any end-of-line characters is determined by the 


_format specified by the MLM_FORMAT message. This format can be one of 


the following values: 
Format Description 


MLFIE_CFTEXT The end-of-line character is formatted as carriage-return/ ~ 
linefeed characters (2 bytes). 


See Also 
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Format Description 


MLFIE_NOTRANS The end-of-line character is formatted as a linefeed char- 
acter (1 byte). 

MLFIE_WINFMT The end-of-line character for hard line breaks is format- 
ted as carriage-return/linefeed characters (2 bytes). The 
end-of-line character for soft line breaks (line breaks 
caused by word-wrapping) is formatted as carriage- 
return/carriage-return/linefeed characters (3 bytes). 


MLM_FORMAT 


m@ MLM_QUERYIMPORTEXPORT New 


Parameters 


Return Value 


Comments 


See Also 


MLM_QUERYIMPORTEXPORT 
mpl = MPFROMP((PBYTE FAR *) ppBuf); /* pointer to buffer */ 
mp2 = MPFROMP((PUSHORT) pcbBuf); /* pointer to buffer size */ 


An application sends an MLM_QUERYIMPORTEXPORT message to deter- 
mine the address and size of the buffer used by the import/export buffer of a 
multiple-line entry field (MLE). The buffer must have been set previously by 
sending an MLM_SETIMPORTEXPORT message (or the returned parameters 
will be invalid). 


ppBuf Low and high word of mp1]. Points to the variable that receives the 
address of the import/export buffer. 


pebBuf Low word of mp2. Points to the variable that receives the size of the 
buffer pointed to by ppBuf. 


The return value is always TRUE. 


The import/export buffer can be used to import to and export text from the 
MLE by using the MLM_IMPORT and MLM_EXPORT messages. 


MLM_EXPORT, MLM_IMPORT, MLM_SETIMPORTEXPORT 


M@ MLM_QUERYLINECOUNT | New 


Parameters 


Return Value 


See Also 


MLM_QUERYLINECOUNT 
mp1 = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYLINECOUNT message to retrieve the 
number of lines in a multiple-line entry field (MLE). 


This message does not use any parameters. 


The return value is a 32-bit value (ULONG) that specifies the number of lines in 
the MLE. _— 


MLM_QUERYTEXTLENGTH 
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MLM_QUERYLINELENGTH New 


Parameters 


Return Value 


Comments 


See Also 


MLM_QUERYLINELENGTH 
mpl = MPFROMLONG(10ffset); /* beginning of count */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYLINELENGTH message to retrieve the 
number of characters between the specified character and the beginning of the 
next line in a multiple-line entry control (MLE). 


lOffset Low and high word of mp1. Specifies the offset (number of characters 
from the beginning of the text) of the first character to count. If this parameter 
is set to - 1, the current cursor position is used as the starting character. 


The return value is a 32-bit value (ULONG) that specifies the number of charac- 
ters between the specified character and the beginning of the next line. If the 
specified character is on the last line of the MLE, the number of characters to 
the end of that line is returned. 


The line break at the end of the line is counted as a single character. 


MLM_QUERYTEXTLENGTH 


MLM_QUERYREADONLY New 


Parameters 


Return Value 


MLM_QUERYREADONLY 
mpl = OL; /7* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYREADONLY message to determine 
whether the multiple-line entry field (MLE) is in read-only mode. While read- 
only mode is set, the user cannot change the contents of the text in the MLE. 


This message does not use any parameters. 


The return value is the read-only state of the MLE. The return value is TRUE 
when read-only mode is set. 


See Also MLM_SETREADONLY 

MLM_QUERYSEL | New 
MLM_QUERYSEL 
mpl = MPFROMSHORT (usQueryMode) ; /* specifies the type of query */ 
mp2 = OL; . /* not used, must be zero a/ 


An application sends an MLM_QUERYSEL message to retrieve the offsets 
(number of characters from the beginning of the text) of the characters selected 
in a multiple-line entry field (MLE). 


Parameters 


Return Value 


Example 


See Also 
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usQueryMode Low word of mp1. Specifies which offset to return. This 
parameter can be one of the following values: 


Value Meaning 


MLFQS_MINMAXSEL Returns the offsets of the selection in a 
single 32-bit value. The high word contains 
the offset of the ending selection charac- 
ter, and the low word will contain the 
offset of the beginning character. These 
values are invalid if the selection contains 
offsets greater than 64K. 


MLFQS_MINSEL Returns the minimum (leftmost) offset of 
the selection. 

MLFQS_MAXSEL Returns the maximum (rightmost) offset of 
the selection. 

MLFQS_ANCHORSEL Returns the offset of the first selected 
character. 

MLFQS_CURSORSEL Returns the offset of the cursor. 


The return value is a 32-bit value; its meaning depends on the setting of the 
usQueryMode parameter. 


This example sends two MLM_QUERYSEL messages to obtain the beginning 
and ending points of the current selection, sends an 
MLM_SETIMPORTEXPORT message to set up the export buffer, and then 
sends an MLM_EXPORT message to export the selection into the buffer. 


LONG 1Start, cch; 
CHAR szBuf [500]; 


1Start = (LONG) WinSendMsg(hwndMle, MLM_QUERYSEL, 
(MPARAM) MLEQS_MINSEL, (MPARAM) OL); 
cch = 1Start - (LONG) WinSendMsg(hwndMle, MLM_QUERYSEL, 
(MPARAM) MLEQS_MAXSEL, (MPARAM) OL); 
WinSendMsg(hwndMle, MLM_SETIMPORTEXPORT, 
(MPARAM) szBuf, (MPARAM) sizeof (szBuf)); ' 
WinSendMsg(hwndMle, MLM_LEXPORT, (MPARAM) &1Start, (MPARAM) &cch); 


MLM_EXPORT, MLM_QUERYSELTEXT, MLM_SETIMPORTEXPORT, 
MLM_SETSEL 


MLM_QUERYSELTEXT New 


Parameters 


Return Value 


MLM_QUERYSELTEXT 
mpl = MPFROMP((PCH) pchBuf); 7* pointer to buffer for selection ee 
mp2 = OL; /7* not used, must be zero 


An application sends an MLM_QUERYSELTEXT message to copy the selec- 
tion from a multiple-line entry field (MLE) into the specified buffer. 


pchBuf Low and high word of mp1. Points to the buffer that receives the 
selected text. 


The return value is a 32-bit value (ULONG) that specifies the number of bytes 
actually placed in the buffer. 
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Comments 


See Also 


The application must ensure that the selected text does not overflow the 
buffer. An application can send an MLM_QUERYSEL message to 
retrieve character offsets of the selection, and then send an 
MLM_QUERYFORMATTEXTLENGTH message to determine the 
number of bytes the selected text occupies. 


MLM_QUERYFORMATTEXTLENGTH, MLM_QUERYSEL 


MLM_QUERYTABSTOP . New 


Parameters 
Return Value 
See Also 


MLM_QUERYTABSTOP 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYTABSTOP message to retrieve the inter- 
val (in pels) at which tab stops are set in a multiple-line entry field (MLE). 


This message does not use any parameters. 
The return value is a 16-bit value (USHORT) that specifies the tab-stop interval. 
MLM_SETTABSTOP 


MLM_QUERYTEXTCOLOR New 


Parameters 


Return Value 


MLM_QUERYTEXTCOLOR 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_QUERYTEXTCOLOR message to obtain the 
color of the text in a multiple-line entry field (MLE). 


This message does not use any parameters. 


The return value is a 32-bit value that indicates the color of the text. It can be 
one of the following values: 


Value Meaning 

CLR_FALSE All color planes are zeros. 

CLR_TRUE All color planes are ones. 
CLR_DEFAULT Default value; same as CLR_NEUTRAL. 
CLR_WHITE White. 

CLR_BLACK Black. 

CLR_BACKGROUND Reset color. 

CLR_BLUE Blue. 

CLR_RED Red. 

CLR_PINK Pink. 


CLR_GREEN Green. 


Return Value 


See Also — 
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Value Meaning 
CLR_CYAN Cyan. 
CLR_YELLOW Yellow. 
CLR_NEUTRAL Neutral. 
CLR_DARKGRAY Dark gray. 
CLR_DARKBLUE Dark blue. 
CLR_DARKRED Dark red. 
CLR_DARKPINK Dark pink. 
CLR_.DARKGREEN Dark green. 
CLR._.DARKCYAN Dark cyan. 
CLR_BROWN Brown. 
CLR_PALEGRAY Light gray. 
See Also MLM_SETTEXTCOLOR 
MLM_QUERYTEXTLENGTH New 
MLM_QUERYTEXTLENGTH . 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 
An application sends an MLM_QUERYTEXTLENGTH message to retrieve the 
number of bytes in a multiple-line entry field (MLE). 
Parameters This message does not use any parameters. 


The return value is a 32-bit value (LONG) that specifies the number of bytes in 
the MLE. This value includes carriage-return and linefeed characters. 


MLM_QUERYFORMATTEXTLENGTH 


MLM_QUERYTEXTLIMIT New 


Parameters 


Return Value 


See Also 


MLM_QUERYTEXTLIMIT 
mpl = OL; 7* not used, must be zero */ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an MLM_QUERYTEXTLIMIT message to retrieve the 
number of characters currently allowed in a multiple-line entry field (MLE). 


This message does not use any parameters. 

The return value is a 32-bit value (LONG) that specifies the maximum number of 
characters currently allowed in the MLE. A return value of - 1 indicates an 
unlimited number of characters are allowed. 


MLM_SETTEXTLIMIT 
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—H MLM_QUERYUNDO New 
MLM_QUERYUNDO 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /7* not used, must be zero */ 


Parameters 
Return Value 


See Also 


An application sends an MLM_QUERYUNDO message to determine if a 
multiple-line entry-field (MLE) operation can be undone. 


This message does not use any parameters. 


The return value is a 32-bit value that indicates whether an MLE operation can 
be undone and, if so, which message can be undone. The low word contains 
TRUE if the message can be undone or FALSE if the message was just undone. 
The high word contains the message, or it contains zero if no message is avail- 
able to be undone. The following messages can be returned: 


Message Description 
MLM_CLEAR Indicates that the last MLM_CLEAR or 
‘ MLM_DELETE message can be undone. 
MLM_CUT Indicates that the last MLM_CUT message can 
be undone. 
MLM_INSERT Indicates that the last MLM_INSERT message 
can be undone. 
MLM_PASTE Indicates that the last MLM_PASTE message 
' can be undone. 
MLM_SETFONT Indicates that the last MLM_SETFONT mes- 
sage can be undone. 
MLM_SETTEXTCOLOR Indicates the last MLM_SETBACKCOLOR 
or MLM_SETTEXTCOLOR message can be 
undone. 
WM_CHAR Indicates that the last character entered by the 


user can be undone. 


MLM_RESETUNDO, MLM_UNDO 


MLM_QUERYWRAP | | New 


Parameters 
Return Value 


See Also 


MLM_QUERYWRAP 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /7* not used, must be zero */ 


An application sends an MLM_QUERYWRAP message to retrieve the current 
state of word-wrapping in a multiple-line entry field (MLE). 


This message does not use any parameters. 


The return value is TRUE if word-wrapping is currently set. It is FALSE if 
word-wrapping is not set. 


MLM_SETWRAP 
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mM MLM_RESETUNDO New 
MLM_RESETUNDO 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_RESETUNDO message to reset (clear) the undo 
flag of a multiple-line entry field (MLE). The undo flag is set whenever an opera- 
tion within the MLE can be undone. 


Parameters This message does not use any parameters. 
Return Value The return value is TRUE if the MLE undo flag is cleared as a result of this 


message. Otherwise, the return value is FALSE, indicating that the undo flag 
was already cleared. 


See Also MLM_QUERYUNDO, MLM_UNDO 
m@ MLM_SEARCH New 
MLM_SEARCH 
mp1 = MPFROMLONG(ulStyle) ; /* search style uj 


mp2 = MPEROMP (pmlesearch) ; /* address of structure with search data */ 


An application sends an MLM_SEARCH message to search for (and optionally 
replace) text within a multiple-line entry field (MLE). 


Parameters ulStyle Low and high word of mp1. Specifies the style of the search. This 
parameter can be any combination of the following values: 


Value Meaning 


MLFSEARCH_CASESENSITIVE Specifies that the search is case-sensitive. 


MLFSEARCH_SELECTMATCH _ Specifies that if the text is found, it should 
be highlighted and scrolled into view (if 


necessary). This is identical to sending the 
MLM_SETSEL message. 


MLFSEARCH_CHANGEALL Specifies that all text found is to be 
replaced by the text in the pchReplace 
field of the MLE_SEARCHDATLA struc- 
ture. 


pmlesearch Low and high word of mp2. Points to the MLE_LSEARCHDATA 
structure that contains the search data. The MLE_LSEARCHDATA structure has 
the following form: 


typedef struct _MLE_SEARCHDATA { 
USHORT cb; 
PCHAR pchFind; 
PCHAR pchReplace; 
SHORT cchFind; 
SHORT cchReplace; 
IPT iptStart; 
IPT iptStop; 
USHORT cchFound; 
} MLE_SEARCHDATA; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


Comments 


Example 


See Also 


The return value is TRUE if the search is successful, or it is FALSE, indicating 
that the search string was not found. 


If the MLFSEARCH_CHANGEALL flag is not set and a match is found, the 
iptStart field of the MLE_SEARCHDATA structure is set to the offset (number 
of characters from the beginning of the text) of the first character that matches 
the search string. The cchFound field is set to the number of characters that 
match the search string. The current cursor position is not changed unless the 


. MLFSEARCH_SELECTMATCH flag is set. 


While the MLE is searching, it periodically sends an MLN_SEARCHPAUSE 
message that contains the current position of the search. You can terminate the 
search by returning TRUE to the MLN_SEARCHPAUSE notification message. 


This example searches for all occurrences of the word bonnie and replaces it 
with the word jeannette: 


MLE_SEARCHDATA search; 

search.cb = sizeof (search) ; 

search.pchFind = "bonnie"; 

search.pchReplace = "jeannette"; 

search.cchFind = 6; 

search.cchReplace = 9; 

search.iptStart = 0; /* from the beginning of the text * 
search.iptStop = -1; /* to the end of the text | 
WinSendMsg(hwndMle, MLM_SEARCH, MLFSEARCH_CHANGEALL, (MPARAM) &search) ; 


MLM_SETSEL, MLN_SEARCHPAUSE, WM_CONTROL 


I MLM_SETBACKCOLOR . New 


Parameters 


MLM_SETBACKCOLOR 
mp1 MPFROMLONG( (COLOR) clr); /* color */ 
mp2 OL; /* not used, must be zero */ 


An application sends an MLM_SETBACKCOLOR message to set the back- 
ground color ofa multiple-line entry field (MLE). 


clr Specifies the color. This parameter can be one of the following values: 


Value Meaning 

CLR_FALSE All color planes are zeros. 

CLR_TRUE . All color planes are ones. 
CLR_DEFAULT Default value; same as CLR_NEUTRAL. 
-CLR_WHITE White. 

CLR_BLACK Black. 

CLR_BACKGROUND Reset color. 

CLR_BLUE Blue. 

CLR_RED Red. 

CLR_PINK Pink. 


CLR_GREEN Green. 


Return Value 


See Also 
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Value Meaning 
CLR_CYAN Cyan. 
CLR_YELLOW Yellow. 
CLR_NEUTRAL Neutral. 
CLR_DARKGRAY Dark gray. 
CLR_DARKBLUE Dark blue. 
CLR_DARKRED Dark red. 
CLR_DARKPINK Dark pink. 
CLR_DARKGREEN Dark green. 
CLR_.DARKCYAN Dark cyan. 
CLR_BROWN Brown. 
CLR_PALEGRAY Light gray. 


The return value is the previous color of the background. 


MLM_QUERYBACKCOLOR, MLM_SETTEXTCOLOR 


MLM_SETCHANGED New 
MLM_SETCHANGED 
mp1 = MPFROMSHORT((BOOL) fChanged) ; /* changed flag a/ 
mp2 = OL; /7* not used, must be zero */ 


Parameters 


Return Value 


See Also 


An application sends an MLM_SETCHANGED message to set or clear the 


multiple-line entry field (MLE) changed flag. 


fChanged Low word of mp1. Specifies whether to set or clear the changed 
flag. A value of TRUE sets the changed flag. 


The return value is the previous state of the MLE changed flag. 
MLM_QUERYCHANGED, MLN_CHANGE, WM_CONTROL 


MLM_SETFIRSTCHAR New 


Parameters 


MLM_SETFIRSTCHAR 
mpl = MPFROMLONG(1l0ffChar) ; 


/* insertion point */ 
mp2 = OL; 


/7* not used, must be zero */ 


An application sends an MLM_SETFIRSTCHAR message to specify the first 
visible character in a multiple-line entry field (MLE). The MLE scrolls the text 
vertically and horizontally as needed to place the character in the upper-left 
corner of the MLE window. 


lOffChar Low and high word of mp1. Specifies the offset (number of charac- 
ters from the beginning of the text) of the character to be placed in the upper- — 
left corner of the MLE window. 
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Return Value The return value is always TRUE. 


Comments If the value specified by the /OffChar parameter is greater than the total number 
of characters in the MLE, the first visible character is set one beyond the last 
character in the MLE. 


See Also MLM_QUERYFIRSTCHAR 

MLM_SETFONT New 
MLM_SETEONT 
mpl = MPFROMP (pfattrs) ; /* pointer to structure with font info. */ 
mp2 = OL; 7/* not used, must be zero */ 


An application sends an MLM_SETFONT message to set the font for a 
multiple-line entry field (MLE). 


Parameters Pfattrs Low and high word of mp1. Points to the FATTRS structure that con- 
tains the font information. The FATTRS structure has the following form: 


typedef struct _FATTRS { 
USHORT usRecordLength; 
USHORT fsSelection; 
LONG lMatch; 
CHAR szFacename [FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG 1MaxBaselineExt; 
LONG lAveCharWidth; 
USHORT fsType; 
USHORT fsFontUse; 

} FATTRS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” - 


Return Value The return value is TRUE if the font is successfully set or FALSE if an error 
occurs. 


Example This example retrieves the current font information, changes it to italic, and sets 
it using the MLM_SETFONT message: 


FATTIRS fat; 

fat.usRecordLength = sizeof (FATTRS) ; 

WinSendMsg(hwndMle, MLM_QUERYFONT, (MPARAM) &fat, (MPARAM) OL); 
fat.fsSelection = FATTR_SEL_ITALIC; 

WinSendMsg(hwndMle, MLM_SETFONT, (MPARAM) &fat, (MPARAM) 0); 


See Also MLM_QUERYFONT 


MLM_SETFORMATRECT New 


MLM_SETEFORMATRECT 
mpl = MPFROMP((PMLEFORMATRECT) pmlefrmrcecl); /* point to format rect. */ 
mp2 = MPFROMLONG((ULONG) f1l0ptions) ; /* options * 


An application sends an MLM_SETFORMATRECT message to set a format 
rectangle in a multiple-line entry field (MLE). The format rectangle can be used 
to limit the insertion of text within the MLE window. 
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Parameters pmlefrmrcl Low and high word of mp1. Points to the MLEFORMATRECT 
structure that contains the format-rectangle dimensions. If this parameter is 
NULL, the current MLE-window dimensions (minus the border or scroll bars) is 
used. The MLEFORMATRECT structure has the following form: 


typedef struct _MLEFORMATRECT { 
LONG cxFormat; 
LONG cyFormat; 

} MLEFORMATRECT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


flOptions Low and high word of mp2. Specifies how the format rectangle is to 
be used. A value of zero causes the MLE to remove any format rectangle and to 
ignore the pmlefrmrcl parameter. Otherwise, this parameter can be a combina- 
tion of the following values: 


Value Meaning 


MLFFMTRECT_LIMITHORZ Specifies that the text within the MLE 
cannot exceed the horizontal dimension 
specified by the pmlefrmrcl parameter. If 
word-wrap mode is turned on before the 
format rectangle is set, lines automatically 
wrap to stay within the horizontal limit of 
the format rectangle. If word-wrap mode is 
turned off before the format rectangle is 
set, an MLN_PIXHORZOVERFLOW 
notification message is sent to the applica- 
tion whenever an operation would exceed 
the horizontal limit specified in the format 
rectangle. 


MLFFMTRECT_LIMITVERT Specifies that the text within the MLE 
' cannot exceed the vertical dimension 
specified by the pmlefrmrcl parameter. 
When an MLE operation would cause 
text to exceed the vertical limit, an 
MLN_PIXVERTOVERFLOW notification 
message is sent to the application. 


MLFFMTRECT_MATCHWINDOW Specifies that the format rectangle is to be 
kept the same size as the MLE window 
(minus the border or scroll bars). 


MLFFMTRECT_FORMATRECT _ Specifies that the format rectangle is to be 
kept the same size as the MLE window 
(minus the border or scroll bars) and that 
text cannot exceed the size of the window. 
This value is equivalent to combining 
the MLFFMTRECT_LIMITHORZ, 
MLFFMTRECT_LIMITVERT, and 
MLFFMTRECT_MATCHWINDOW 
values. 


Return Value The return value is TRUE if the text fits within the new format-rectangle dimen- 
sions. Otherwise, it is FALSE, indicating that the text does not fit and that the 
format rectangle is not set. 


Comments 


See Also 
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Whenever an insertion would cause the text to be too long for the MLE, the 
MLN_PIXVERTOVERFLOW or MLN_PIXHORZOVERFLOW notification 
message is sent. 


MLM_QUERYFORMATRECT, MLN_PIXHORZOVERFLOW, 
MLN_PIXVERTOVERFLOW, WM_CONTROL 


MLM_SETIMPORTEXPORT | New 


Parameters 


Return Value 


MLM_SETIMPORTEXPORT ; 
mpl = MPFROMP((PBYTE) pBuf) ; /* pointer to buffer */ 
mp2 = MPEROMSHORT ( (USHORT) CbBuf) ; /* buffer size */ 


An application sends an MLM_SETIMPORTEXPORT message to set the 
transfer buffer for a multiple-line entry field (MLE). 


pBuf Low and high word of mp]. Points to the buffer to be used by the 
MLM_IMPORT, MLM_EXPORT, and MLM_SEARCH messages. 


cbBuf Low word of mp2. Specifies the size (in bytes) of the buffer pointed to 
by the pBuf parameter. The largest size that can be specified is 65,535. 


The return value is always TRUE. 


See Also MLM_EXPORT, MLM_IMPORT 

MLM_SETREADONLY New 
MLM_SETREADONLY . 
mpl = MPFROMSHORT(fReadOnly) ; 7* read-only flag - 
mp2 = OL; /7* not used, must be zero */ 
An application sends an MLM_SETREADONLY message to set the read-only 
state of a multiple-line entry field (MLE). While the read-only state is set, the 
user cannot change the contents of the MLE text. 

Parameters fReadOnly Low word of mp1. Specifies the read-only state of the MLE. A 


Return Value 


See Also 


value of TRUE sets the read-only state. 

The return value is the previous.value of the read-only state. If the return value 
is zero, the read-only state was turned off. If the return value is nonzero, the 
read-only state was turned on. 


MLM_QUERYREADONLY 
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mM MLM_SETSEL New 
MLM_SETSEL 
mpl = MPFROMLONG(10ffsetBegin) ; /* offset of beginning character */ 
mp2 = MPFROMLONG(10ffsetEnd) ; /* offset of ending character */ 


Parameters 


Return Value 


Comments 


Example 


See Also 


Parameters 
Return Value 
See Also 


An application sends an MLM_SETSEL message to select an area of text within 
a multiple-line entry field (MLE). 


lOffsetBegin Low and high word of mp1. Specifies the offset (number of char- 
acters from the beginning of the text) of the first character. If this parameter is 
set to - 1, the current cursor position is used. 


lOffsetEnd Low and high word of mp2. Specifies the offset of the character 
just beyond the selection, where the cursor is to be placed. If this parameter is 
set to - 1, the current cursor position is used. 


The return value is always TRUE. 


The MLE scrolls the text vertically and horizontally as needed to make the selec- 
tion visible. 


If the /OffsetEnd parameter is greater than the lOffsetBegin parameter, the cursor 
is placed to the right of the selected text. If lOffsetEnd is less than lOffsetBegin, 
the cursor is placed to the left of the selected text. 


Character offsets are zero-based. Therefore, the first character has an offset of 
zero. 

This example highlights the second, third, and fourth characters of the text, and 
places the cursor to the right of the fourth character. 

WinSendMsg(hwndMle, MLM_SETSEL, (MPARAM) 1L, (MPARAM) 4L); 


MLM_QUERYSEL 


MLM_SETTABSTOP New 


MLM_SETTABSTOP 
mpl = OE one BORE (USHORT? usTabInterval) ; /* tab-stop interval */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_SETTABSTOP message to set the interval (in 
pels) at which tab stops are placed in a multiple-line entry field (MLE). 


usTabInterval Low word of mp1. Specifies the interval (in pels) for tab stops. 
The return value is a 16-bit value (USHORT) that specifies the tab-stop interval. 
MLM_QUERYTABSTOP 
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™ MLM_SETTEXTCOLOR New 
MLM_SETTEXTCOLOR 
mp1 = MPFROMLONG( (COLOR) clr); /* color */ 
mp2 = OL; /* not used, must be zero */ 


Parameters 


Return Value 


An application sends an MLM_SETTEXTCOLOR message to set the text color 
of a multiple-line entry field (MLE). 


clr Specifies the color. This parameter can be one of the following values: 


Value Meaning 
CLR_FALSE All color planes are zeros. 
CLR_TRUE - All color planes are ones. 
CLR_DEFAULT Default value; same as CLR_NEUTRAL. © 
CLR_WHITE White. 
CLR_BLACK Black. 
CLR_BACKGROUND Reset color. 
CLR_BLUE Blue. 
CLR_RED Red. 
CLR_PINK Pink. 
CLR_GREEN Green. 
CLR_CYAN Cyan. 
CLR_YELLOW Yellow. 
CLR_NEUTRAL Neutral. 
CLR_.DARKGRAY Dark gray. 
CLR_DARKBLUE Dark blue. 
CLR_DARKRED Dark red. 
CLR_DARKPINK Dark pink. 
CLR_DARKGREEN Dark green. 
CLR_DARKCYAN Dark cyan. 

- CLR_BROWN Brown. 
CLR_PALEGRAY: Light gray. 


The return value is the previous color of the text. 


See Also MLM_QUERYTEXTCOLOR, MLM_SETBACKCOLOR 
| MLM_SETTEXTLIMIT New 


MLM_SETTEXTLIMIT 
mpl = MPFROMLONG (cch) ; /* maximum number of characters ms 
mp2 = OL; /7/* not used, must be zero */ 


An application sends an MLM_SETTEXTLIMIT message to set the text size of 
a multiple-line entry field (MLE). The MLE does not accept any characters 
beyond this limit. 


Parameters 


Return Value 


MLM_UNDO = 235 


cch_ Low and high word of mp1. Specifies the maximum number of characters 
allowed in the MLE. A value of - 1 specifies unlimited text is allowed. 


The return value is zero if the current MLE text is less than the new limit. Oth- 
erwise, the return value is the number of characters that exceed the specified 
limit, and the limit is not set. 


Comments If the user inserts more text than the specified maximum for the MLE, an 
MLN_TXTOVERFLOW message is sent. If the application inserts more text 
than the specified maximum, an MLN_OVERFLOW notification message is 
sent. 

See Also MLM_QUERYTEXTLIMIT, MLN_OVERFLOW, MLN_TEXTOVERFLOW, 
WM_CONTROL 

MLM_SETWRAP New 
MLM_SETWRAP 
mpl = MPFROMSHORT (fWrap) ; /* word-wrap flag */ 
mp2 = OL; /* not used, must be zero */ 

An application sends an MLM_SETWRAP message to set word-wrap mode in a 
multiple-line entry field (MLE). 

Parameters fWrap Lowword of mp1. Specifies whether to turn word-wrap mode on or 


Return Value 


Comments 


See Also 


MLM_UNDO 


off. If this parameter is TRUE, word-wrapping is turned on. If it is FALSE, 
word-wrapping is turned off. 


The return value is TRUE if word-wrap mode is set as a result of this message. 
Otherwise, the return value is FALSE, indicating that the word-wrap mode can- 
not be changed. 


Word-wrap mode affects only the visual display of the text. Line breaks inserted 
by the user are not affected. 


Word-wrap mode cannot be turned off while the text exceeds the format rect- 
angle specified in the MLM_SETFORMATRECT message. Word-wrap mode 
cannot be turned on if the result of word-wrapping would cause the text to 


exceed the format rectangle specified in the MLM_SETFORMATRECT mes- 
sage. 


MLM_QUERYWRAP, MLM_SETFORMATRECT 


New 


Parameters 


MLM_UNDO 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an MLM_UNDO message to undo a multiple-line entry- 
field (MLE) operation. . 


This message does not use any parameters. 
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Return Value The return value is TRUE if an MLE operation is undone. 


Comments Only the following MLE operations can be undone: 


MLM_CLEAR 
MLM_CUT 
MLM_DELETE 
MLM_INSERT 
MLM_PASTE 
MLM_SETBACKCOLOR 
MLM_SETFONT 
MLM_SETTEXTCOLOR 
MLM_UNDO 
WM_CHAR 


If an MLM_UNDO message is sent when the undo flag has been cleared, it rev- 
erses the previous undo operation. 


See Also MLM_QUERYUNDO, MLM_RESETUNDO 

MLN_CHANGE New 
WM_CONTROL . 
id = (USHORT) SHORT1EROMMP eter): /* MLE-window ID */ 


usNotifyCode = MLN_CHANGE 


The MLN_CHANGE notification message is sent whenever the text ina 
multiple-line entry field (MLE) changes. 


Parameters id Low word of mp1. Identifies the MLE window. 
usNotifyCode High word of mp1. Set to MLN_CHANGE. 
See Also MLM_QUERYCHANGED, MLM_SETCHANGED, WM_CONTROL 
MLN_CLPBDFAIL New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* MLE-window ID */ 
usNotifyCode = MLN_CLPBDEAIL; 
sError = (USHORT) SHORT1FROMMP (mp2) ; /* error code a/ 


The MLN_CLPBDFAIL notification message is sent if the clipboard is unable to 
receive the text sent to it by a multiple-line entry field (MLE). 


Parameters id Low word of mp1]. Identifies the MLE window. 
usNotifyCode High word of mp1. Set to MLN_CLPBDFAIL. 


See Also 


MLN_KILLFOCUS 237 


sError Specifies the error that occurred. This parameter can be one of the 
following error values: 


Value Meaning 


MLFCLPBD_TOOMUCHTEXT Specifies that the amount of text exceeds 
the capacity of the clipboard. 


MLFCLPBD_ERROR Specifies an unknown clipboard error. 
MLM_COPY, MLM_CUT, WM_CONTROL 


MLN_HSCROLL 


Parameters 


Return Value 


New 


MLN_HSCROLL 


id = (USHORT) SHORT1FROMMP (mp1) ; /* scroll-bar window ID */ 
usNotifyCode = MLN_UNDOOVERFLOW; 
sPos = (USHORT) SHORTIFROMMP (mp2) ; /* slider position a/ 


The MLN_HSCROLL notification message is sent to the owner of the multiple- 
line entry field (MLE) window when a horizontal scroll event occurs. 


id Low word of mp1. Identifies the scroll-bar window. 
usNotifyCode Wigh word of mp1. Set to MLN_HSCROLL. ~ 


SPos Low word of mp2. Specifies the number of pels of text (nonvisible) to 
the left of the window. 


An application should return zero if it processes this message. 


See Also MLN_VSCROLL, WM_CONTROL 

MLN_KILLFOCUS New 
WM_CONTROL 
id = (USHORT) SHORTIFROMMP(mp1); /* MLE-window ID */ 
usNotifyCode = MLN_KILLFOCUS; 
The MLN_KILLFOCUS notification message is sent whenever the window in a 
multiple-line entry field (MLE) window loses the input focus. 

Parameters id Low word of mp1. Identifies the MLE window. 


Return Value 


See Also 


usNotifyCode High word of mp1. Set to MLN_KILLFOCUS. 


An application should return zero if it processes this message. 


MLN_SETFOCUS, WM_CONTROL 


MLN_MARGIN 


Parameters 


Return Value 


Return Value 
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New 
WM_CONTROL 
id = (USHORT) gy seca nr ee /* MLE-window ID */ 
usNotifyCode = MLN_MARGIN; 
pmrg = (PMARGSTRUCT) PVOIDEROMMP (mp2) ; /* pointer to MLEMARGSTRUCT */ 


The MLN_MARGIN notification message is sent when the mouse moves over 
one of the margins of a multiple-line entry field (MLE). 


id Low word of mp1. Identifies the MLE window. 


usNotifyCode High word of mp1. Set to MLN_MARGIN. 


pmrg_ Low and high word of mp2. Points to the MLEMARGSTRUCT structure 
that contains the margin data. The MLEMARGSTRUCT structure has the fol- 
lowing form: 


typedef struct  _MLEMARGSTRUCT { 
USHORT afMargins; 
USHORT usMouMsg; 
IPT iptNear; 

} MLEMARGSTRUCT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


An application should return zero if you want the MLE to process this message. 


See Also WM_CONTROL 
MLN_MEMERROR New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP(mp1); /* MLE-window ID */ 
usNotifyCode = MLN_MEMERROR; 
The MLN_MEMERROR notification message is sent if there is insufficient 
memory for the requested operation within a multiple-line entry field (MLE). 
Parameters id Low word of mp1. Identifies the MLE window. 


usNotifyCode High word of mp1. Set to MLN_-MEMERROR. 


An application should return zero if it processes this message. 


See Also WM_CONTROL 

MLN_OVERFLOW | New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* MLE-window ID +/ 
usNotifyCode = MLN_OVERFLOW; 
pmleover = (PMLEOVERFLOW) PVOIDFROMMP (mp2); /* point to MLEOVERFLOW *#/ 
The MLN_OVERFLOW notification message is sent when an operation in a 
multiple-line entry field (MLE) would overflow a text limit or a format rectangle. 

Parameters id Low word of mp1. Identifies the MLE window. 


Return Value 
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usNotifyCode High word of mp1. Set to MLN_LOVERFLOW. 


pmleover Low and high word of mp2. Points to an MLEOVERFLOW struc- 
ture. The MLEOVERFLOW structure has the following form: 


typedef struct _MLEOVERFLOW { 
ULONG afErrInd; 
LONG nBytesOver ; 
LONG pixHorzOver; 
LONG pixVertOver; 
} MLEOVERELOW; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


The application should return TRUE to retry the operation. 


Comments Before returning TRUE, the application should perform some operation (for 
example, changing the dimensions of the format rectangle) that will enable the 
text to fit. 

Overflow caused by user-inserted text results in a MLN_PIXHORZOVERFLOW 
or MLN_VERTOVERFLOW notification message. Overflow caused by an appli- 
cation sending a message to the MLE results in a MLN_.OVERFLOW message. 

See Also MLN_PIXHORZOVERFLOW, MLN_PIXVERTOVERFLOW, 
WM_CONTROL 

MLN_PIXHORZOVERFLOW New 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* MLE-window ID */ 
usNotifyCode = MLN_PIXHORZOVERELOW; 
lOverElow = LONGEROMMP (mp2) ; /* amount of overflow */ 

The MLN_PIXHORZOVERFLOW notification message is sent whenever user 
uses the keyboard to insert more text than can fit in the current format rectangle 
or the text limit of a multiple-line entry field (MLE). 

Parameters id Low word of mp1. Identifies the MLE window. 


Return Value 


Comments 


See Also 


usNotifyCode High word of mp1. Set to MLN_PIXHORZOVERFLOW. 


lOverFlow Low and high word of mp2. The number of pels by which the 
operation overflows the current format rectangle. 


An application should return TRUE to retry the operation. If the application 
returns FALSE, the user cannot insert additional text. 


Before returning TRUE, the application should perform some operation (for 
example, changing the dimensions of the format rectangle) that will enable the 
text to fit. 


MLN_OVERFLOW, MLN_PIXVERTOVERFLOW, WM_CONTROL 
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mM MLN_PIXVERTOVERFLOW New 
Pe Se EO 
WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* MLE-window ID */ 
usNotifyCode = MLN_PIXVERTOVERFLOW; 
lOverFlow = LONGEROMMP (mp2) ; /* amount of overflow */ 


Parameters 


Return Value 


The MLN_PIXVERTOVERFLOW notification message is sent whenever a user 
uses the keyboard to insert more text than can fit in the current format rectangle 
or text limit of a multiple-line entry field (MLE). 

id Low word of mp1. Identifies the MLE window. 

usNotifyCode High word of mp1. Set to MLN_PIXVERTOVERFLOW. 
lOverFlow Low and high word of mp2. The number of pels by which the 
operation overflowed the current format rectangle. 


An application should return TRUE to retry the operation. If the application 
returns FALSE, the user cannot insert additional text. 


Comments Before returning TRUE, the application should perform some operation (for 
example, changing the dimensions of the format rectangle) that will enable the 
text to fit. 

Example This example processes the MLN_PIXVERTOVERFLOW message by increas- 
ing the size of the format rectangle: 

MLEFORMATRECT mlefr; 
case MLN_PIXVERTOVERELOW: 

mlefr.cyFormat += 100; 

WinSendMsg(hwndMle, MLM_SETFORMATRECT, (MPARAM) &mlefr, 

(MPARAM) MLEEMTRECT_LIMITVERT) ; 
return TRUE; 
See Also MLN_PIXHORZOVERFLOW, WM_CONTROL 
mM MLN_SEARCHPAUSE New 

WM_CONTROL 
id = (USHORT) SHORT1FROMMP (mp1) ; /* MLE-window ID + / 
usNotifyCode = MLN_SEARCHPAUSE ; 
1CurOffset = (ULONG) LONGFROMMP (mp2) ; /* position of search */ 
The MLN_SEARCHPAUSE notification message is sent periodically while a 
multiple-line entry field (MLE) searches as a result of an MLM_SEARCH mes- 
sage. An application can use this message to terminate the search. 

Parameters id Low word of mp1. Identifies the MLE window. 


Return Value 


See Also 


usNotifyCode High word of mp1. Set to MLN_SEARCHPAUSE. 


ICurOffset Low and high word of mp2. Specifies the offset (number of charac- 
ters from the beginning of the text) of the current character being searched for. 


The application should return FALSE to continue the search or TRUE to ter- 
minate the search. 


MLM_SEARCH, WM_CONTROL 
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m@ MLN_SETFOCUS New 
WM_CONTROL 


Parameters 


Return Value 


id = (USHORT) SHORT1EROMMP (mp1) ; /* MLE-window ID */ 
usNotifyCode = MLN_SETEFOCUS; 


The MLN_SETFOCUS notification message is sent when the window in a 
multiple-line entry field (MLE) receives the input focus. 


id Low word of mp1. Identifies the MLE window. 
usNotifyCode High word of mp1. Set to MLN_SETFOCUS. 


An application should return zero if it processes this message. 


See Also MLN_KILLFOCUS, WM_CONTROL 
@ MLN_TEXTOVERFLOW New 

WM_CONTROL 
id = (USHORT) SHORT1EFROMMP (mp1) ; /* MLE-window ID */ 
usNotifyCode = MLN_TEXTOVERFLOW 
cchOver = (ULONG) LONGFROMMP (mp2) ; /* characters over limit */ 
The MLN_TEXTOVERFLOW notification message is sent when an operation in 
a multiple-line entry field (MLE) exceeds the current text limit. 

Parameters id Low word of mp1. Identifies the MLE window. 


Return Value 


usNotifyCode High word of mp1. Set to MLN_TEXTOVERFLOW. 


cchOver Low and high word of mp2. Specifies the number of characters by 
which the text limit would overflow if the present operation completes. 


An application should return TRUE to retry the operation. If the application 
returns FALSE, the user cannot insert additional text. 


Comments Before returning TRUE, the application should perform some operation (for 
example, changing the dimensions of the format rectangle) that will enable the 
text to fit. 

See Also MLN_.OVERFLOW, WM_CONTROL 

—@ MLN_UNDOOVERFLOW New 
WM_CONTROL 

-id = (USHORT) SHORTIFROMMP(mp1); /* MLE-window ID */ 

usNotifyCode = MLN_UNDOOVERELOW; 
The MLN_UNDOOVERFLOW notification message is sent by a multiple-line 
entry field (MLE) if a text change cannot be undone because the amount of text 
involved exceeds the undo limit. This includes text entry, deletion, and cutting 
and pasting. 

Parameters id Low word of mp1. Identifies the MLE window. 
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Return Value 


See Also 


MLN_VSCROLL 


Parameters 


Return Value 
See Also 


usNotifyCode High word of mp1. Set to MLN.UNDOOVERFLOW. 
An application should return zero if it processes this message. 


MLM_CUT, MLM_DELETE, MLM_INSERT, MLM_PASTE, 
WM_CONTROL 


New 


MLN_VSCROLL 


id = (USHORT) SHORT1FROMMP (mp1) ; /* control-window ID *#/ 
usNotifyCode = MLN_UNDOOVERFLOW; 
sPos = (USHORT) SHORT1FROMMP (mp2) ; /* slider position */ 


The MLN_VSCROLL notification message is sent to the owner of a multiple- 
line entry field (MLE) window when a vertical scroll event occurs. 


id Low word of mp1. Identifies the MLE window. 
usNotifyCode High word of mp1. Set to MLN_VSCROLL. 
sPos Low word of mp2. Specifies the top line of the display text. 


An application should return zero if it processes this message. 


MLN_HSCROLL, WM_CONTROL 


MM_DISMISSMENU New 


Parameters 
Return Value 
See Also 


MM_DISMISSMENU 
mpl = OL; 7* not used, must be zero */ 
mp2 = OL; 7* not used, must be zero */ 


An application sends an MM_DISMISSMENU message to dismiss a pull-down 
menu. Ordinarily, an application sends this message only to a pull-down menu 
that has the MIA_NODISMISS attribute. 

This message does not use any parameters. 


This message does not return a value. 


MM_ENDMENUMODE 


MM_QUERYSELITEMID Change 


Parameters 


MM_QUERYSELITEMID 
mp1 = MPFROM2SHORT( (BOOL) fIncludeSubMenus, 0); 
mp2 = OL; /7* must be zero *#/ 


An application sends an MM_QUERYSELITEMID message to determine the 
identifier of the selected menu item. 


fincludeSubMenus High word of mp1. Specifies whether to include submenus 
in the search. A value of TRUE includes submenus. 
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Return Value The return value is the identifier of the selected item, MIT_NONE if no item is 
selected, or MID_ERROR if an error occurs. 


See Also MM_SELECTITEM 
Changes The fIncludeSubMenus parameter has been added. 
MOU_DISPLAYMODECHANGE New 


USHORT DosDevlOCtl( OL, OL, Ox005D, 0x0007, hDevice) 
HFILE hDevice; /« device handle «/ 


The MOU_DISPLAYMODECHANGE function notifies the mouse device 
driver that a display-mode change is complete. 


Parameters hDevice Identifies the pointing device that receives the device-control func- 
tion. This handle must have been created previously by using the DosOpen func- 
tion. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

Comments. The MOU_DISPLAYMODECHANGE function notifies the mouse that a mode 


switch is complete and that drawing is allowed. The pointer is redrawn if it was 
hidden when the mode switch began. ° 


See Also DosDevIOCtl, DosOpen, VioSetMode 
MOU_SETPROTDRAWADDRESS . Change 
USHORT DosDeviOCtl( pbDrawData, pbFunction, 0x005A, 0x0007, hDevice) 

PBYTE pbDrawData; __/« pointer to drawing data »/ 

PBYTE pbFunction; /+ pointer to structure with drawing function «/ 

HFILE hDevice; /« device handle »/ 


The MOU_SETPROTDRAWADDRESS function notifies the mouse device 
driver of the address of a protected-mode pointer-draw function. This function is 
valid for protected mode only. 


Parameters pbDrawData Points to the PTRDRAWDATA structure. This structure has the 
following form: 


typedef struct _PTRDRAWDATA { 


USHORT cb; /* length */ 
USHORT usConfig; /* which display to draw on */ 
USHORT usFlag /* Application/BVS Flag */ 


} PTRDRAWDATA; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pbFunction Points to the PTRDRAWFUNCTION structure that contains the 
address of the pointer-draw function. This structure has the following form: 


typedef struct _PTRDRAWFUNCTION { 
PEN pfnDraw; 
PCH pchDataSeg; 

} PTRDRAWFUNCTION; 
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hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen func- 


tion. 
Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments The pointer-draw routine is an installed, pseudo-character device driver. The 


mouse handler must do the following: 


m Open the pointer-draw device driver. 
M Query the pointer-draw device driver for the address of its entry point. 


m™ Pass the resulting address of the pointer-draw entry point to the mouse 
device driver that uses this function. 


See Also DosOpen, MOU_SETREALDRA WADDRESS 


Changes The first parameter of the DosDevIOCtl function is now pbDrawData, which 
points to a PTRDRAWDATA structure. 


MOU_SETREALDRAWADDRESS | Change 


USHORT DosDevlOCtl( pvConfig, pbFunction, Ox005B, 0x0007, hDevice) 
PVOID pvConfig; /« pointer to configuration structure «/ 
PBYTE pbFunction; /« pointer to structure with function «/ 
HFILE /hDevice; /« device handle s/ 


The MOU_LSETREALDRAWADDRESS function notifies the real-mode mouse 
device driver of the entry point of a real-mode pointer-draw routine. This func- 
tion is intended for use by Session Manager at the end of system initialization 
and is valid for real mode only. 


‘Parameters pvConfig Points to the VIOCONFIGINFO structure that contains information 
about configuration of the default display. The VIOCONFIGINFO structure has 
the following format: 


typedef struct _VIOCONFIGINEO { 

USHORT cb ; 
USHORT adapter; 
USHORT display; 
ULONG cbMemory; 
USHORT Configuration; 
USHORT VDHVersion; 
USHORT Flags; 
ULONG HWBu f ferSize; 
ULONG . FullSaveSize; 
ULONG PartSaveSize; 
USHORT EMAdaptersOFF; 
USHORT EMDisplaysOFF; 

} VIOCONFIGINEO; , 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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pbFunction Points to the PTRDRAWFUNCTION structure that contains the 
address of the pointer-draw function. The PTRDRAWFUNCTION structure has 
the following form: _ 
typedef struct _PTRDRAWFUNCTION { 

PEN pfnDraw; 


PCH pchDataSeg; 
} PTRDRAWFUNCTION; 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen func- 
tion. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, MOU_SETPROTDRAWADDRESS 
Changes The first parameter now points to a VIOCONFIGINFO structure. 


MOU_UPDATEDISPLAYMODE Change 


USHORT DosDevlOCtl( pvConfiginfo, pviomi, 0x0051, 0x0007, hDevice) 
PVOID pvConfiginfo; /« pointer to structure with configuration info «/ 
PVIOMODEINFO pviomi; /» pointer to structure with screen mode »/ 
HFILE hDevice; /« device handle a/ 


The MOU_UPDATEDISPLAYMODE function notifies the mouse device driver 
that the display mode has been modified. 


Parameters pvConfigInfo Points to the VIOCONFIGINFO structure that contains the 
current display-configuration information. The VIOCONFIGINFO structure has 
the following form: 


typedef struct _VIOCONFIGINFO { 

USHORT cb; 
USHORT adapter; 
USHORT display; 
ULONG cbMemory; 
USHORT Configuration; 
USHORT VDHVersion; 
USHORT Flags; 
ULONG HWBuf ferSize; 
ULONG FullSaveSize; 
ULONG PartSaveSize; 
USHORT EMAdaptersOFF; 
USHORT EMDisplaysOFF; 

} VIOCONFIGINEFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


Comments 


See Also 
Changes 


MOU_VER 


pviomi Points to the VIOMODEINFO structure that contains the display- 


mode information. The VIOMODEINFO structure has the following form: 
typedef struct _VIOMODEINFO { 
USHORT cb; 

UCHAR fbType; 

UCHAR color; 

USHORT col; 

USHORT row; 

USHORT hres; 

USHORT vres; 


UCHAR fmt_ID; 

UCHAR attrib; 

ULONG buf_addr; 

ULONG buf_length; 
ULONG) full_length; 
ULONG partial_length; 


PCH ext_data_addr; 
} VIOMODEINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. This handle must have been created previously by using the DosOpen func- 
tion. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


When the video I/O subsystem or registered video I/O subsystem sets the 
display mode, it must notify the mouse device driver prior to switching display 
modes, in order to synchronize the mouse device driver’s functions that update 
the pointer. 


DosOpen, VioSetMode 


This function has been updated to reflect changes to the VIOMODEINFO and 
VIOCONFIGINFO structures, 


New 


USHORT DosDevlOCtlI( pusVersion, OL, Ox006A, 0x0007, hDevice) 


PUSHORT pusVersion; 


HFILE hDevice; 


Parameters 


Return Value 


/« pointer to version number «/ 
/« device handle »/ 


The MOU_VER function returns the version number of the mouse driver. 
pusVersion Points to a data area in which the version number of the mouse 
driver is returned. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. This handle must have been created previously by using the DosOpen func- 
tion. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


Comments 
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The MOU_VER function returns 0x0001 as the version number of the mouse 


driver to indicate that the following features are supported. These features are 
new for MS OS/2, version 1.2. 
Function Change 
MOU_DISPLA YMODECHANGE New IOCtl function. 
MOU_SETPROTDRAWADDRESS New pbDrawData parameter. 
MOU_SETREALDRAWADDRESS New pvConfig parameter. 
MOU_UPDATEDISPLAYMODE New pvConfiginfo parameter. 
MOU_UPDATEDISPLAYMODE Size of VIOMODEINFO structure 
increased from 12 to 34 bytes. 
MOU_VER New IOCtl function. 
The MOU_VER function should be used to determine the version number of the 
mouse device driver before any of these features are used, in order to maintain 
compatibility with earlier versions of MS OS/2. 
See Also DosDevIOCtl, DosOpen 
MouGetNumQueEl Correction 


USHORT MouGetNumQueEl( pmoudi, hmou) 
PMOUQUEINFO pmoudi; /» pointer to structure for number of events »/ 


HMOU hmou; 


Parameters 


Return Value 


Example 


/« mouse handle s/ 


The MouGetNumQueEF! function retrieves the number of events in the mouse- 
event queue. 


' pmougdi Points to the MOUQUEINFO structure that receives the number of 


events in the mouse-event queue. The MOUQUEINFO structure has the follow- 
ing form: 
typedef struct _MOUQUEINFO { 

USHORT cEvents; 


USHORT cmaxEvents; 
} MOUQUEINFO; 


hmou Identifies the mouse. This handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle, enables the mouse pointer to be drawn, 
and runs within an infinite for loop until there are no events in the queue: 
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See Also 


Corrections 


MouSynch 


HMOU hmou; 
MOUEVENTINEO mouevEvent; 
MOUQUEINFO mouqi; 


.USHORT fWait = FALSE; 


MouOpen(OL, &hmou) ; 
MouDrawPtr (hmou) ; 


for (:; 
Noite Nand qer emcees, hmou) ; /* retrieves queue a/ 
if (mouqi.cEvents > 1) 7* until the last queue... */ 
MouReadEventQue (&mouevEvent, &fWait, hmou) ; 
else 
break; 


} 
MouFlushQue, MouOpen, MouReadEventQue 


The example was lacking a closing parenthesis at the end of the MouGetNum- © 
QueE]l function call. This has been added. 


Correction 


USHORT MouSynch( fWait) 


USHORT /fWait; 


Parameters 


Return Value 


Comments 


See Also 


/» wait/no-wait flag »/ 


The MouSynch function synchronizes access to the mouse. This function should 
be used by a Mou subsystem to prevent more than one process from accessing 
the mouse handle at any one time. 


fWait Specifies whether to wait if the mouse device driver is currently busy. If 
this parameter is FALSE, the function returns control immediately without wait- 
ing for the device to become free. If this parameter is TRUE, the function waits 
until the mouse handle is free. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The MouSynch function requests an exclusive system semaphore that clears 
when the Mou subsystem returns to the mouse router. The MouSynch function 
blocks all other threads within a screen group until the semaphore clears. 


A registered mouse subsystem should not issue the MouSynch function when the 
base video subsystem (BVS) issues MouOpen and MouClose functions. A 
registered mouse subsystem must provide the required level of serialization for 
the MouOpen and MouClose functions without calling MouSynch. This special 
processing is required because MouOpen and MouClose are issued by BVS on 
the VioSetMode path. The VioSetMode function can be issued, in turn, by a 
VioSavRedrawWait thread. You can assume the synchronization semaphore was 
already held by another thread blocked by a call to the MouReadEventQue func- 
tion. 


Note that if a save/redraw wait thread issues the VioSetMode function, and if 
BVS in turn issues the MouOpen or MouClose function and the mouse subsys- 
tem in turn issues the MouSynch function, the screen switch will be blocked and 
the system will “hang.” 


DosCloseSem, DosDevIOCtl, MouClose MouOpen, MouReadEventQue, 
MouRegister, VioSayRedrawWait, VioSetMode 


Corrections 


all Piclchg 
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A registered mouse subsystem should not issue MouSynch when the base video 
subsystem (BVS) issues MouOpen and MouClose functions. A registered mouse 
subsystem must provide the required level of serialization for MouOpen and 
MouClose without calling MouSynch. This special processing is required 
because MouOpen and MouClose are issued by BVS on the VioSetMode path. 
The VioSetMode function can be issued, in turn, by a VioSavRedrawWait 
thread. You can assume the synchronization semaphore was already held by 
another thread blocked by a call to MouReadEventQue. 


Note that if a save/redraw wait thread issues the VioSetMode function, if BVS 
in turn issues the MouOpen or MouClose function, and the mouse subsystem in 
turn issues the MouSynch function, the screen switch will be blocked and the 
system will “hang.” 


BOOL Piclchg( hab, pszSrcFile, pszDestFile, Type) 


HAB hab; 

PSZ pszSrcFile; 
PSZ pszDestFile; 
LONG /Type; 


Parameters 


Return Value 


Comments 


New 
/« anchor-block handle »/ 
/» pointer to source-file name »/ 
/« pointer to destination-file name «/ 
/« translation type »/ 


The PicIchg function converts an interchange file to a metafile, or converts a 
symbol file to a font file. 


hab Identifies the anchor block. 


pszSrcFile Points to the string that contains the name of the source file. This 
name must be a valid MS OS/2 filename. 


pszDestFile Points to the string that contains the name of the destination file. 
This name must be a valid MS OS/2 filename. 


lIType Specifies the type of conversion requested. This parameter can be one 
of the following values: 


Value Meaning ; 
PIC_PIFTOMET Converts an interchange file to a metafile. 
PIC_SSTOFONT Converts a symbol set to a font. 


The return value is TRUE if the conversion is successful or FALSE if an error 
occurs. ‘ 


Any reference to an internal symbol or pattern set is changed to a reference to 
the default font character set. Any reference to a line-type set is changed to a 
reference to the default line type. 


Only outline fonts are supported. 
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PicPrint New 
BOOL PicPrint( hab, pszSrcFile, IType, pszParms) 
HAB hab; /» anchor-block handle s/ 
PSZ_.pszSrcFile; /« pointer to source-file name »/ 
LONG /Type; /» type of file to print »/ 
PSZ pszParms; /« spooler parameters »/ 


The PicPrint function prints a picture file. 


Parameters hab Identifies the anchor block. 


pszSrcFile Points to the string that contains the name of the source file. This 
name must be a valid MS OS/2 filename. 


IType _ Specifies the type of file to print. This parameter can be one of the fol- 
lowing values: 


Value Meaning 
_ PIP_MF Prints a metafile. 
PIP_PIF Prints an interchange file. 


pszParms Points to the string that contains spooler parameters. 


Return Value The return value is TRUE if the print operation is successful or FALSE if an 
error occurs. 


PL_ALTERED . New 


PL_ALTERED 
hiniUser = HWNDEROMMP (mp1) ; /* handle of user-profile file */ 
‘hiniSystem = HWNDEROMMP (mp2); /* handle of system-profile file */ 


A PL_ALTERED message is broadcast to all frame windows when an applica- 
tion calls the PrfReset function. 


Parameters hiniUser Low and high word of mp1. Identifies the user-profile file. 
hiniSystem Low and high word of mp2. Identifies the system-profile file. 

Return Value An application should return zero if it processes this message. 

See Also PrfReset 

PrfAddProgram | New 

HPROGRAM PrfAddProgram( hini, pprogde, hGroup) 

HINI ini; /x initialization-file handle »/ 

PPROGDETAILS pprogde; /« address of structure with program information «/ 

HPROGRAM hGroup; /« program-group handle »/ 


The PrfAddProgram function adds a program to the program list of a group in 
Desktop Manager. The same program title can be used in different groups, but 
the program titles within a group must each be unique. 
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Parameters hini Identifies the file to which the program information is added. This param- 
eter can be an initialization-file handle obtained by using the PrfOpenProfile 
function, or it can be the value HINILUSERPROFILE, specifying the user- 
profile file. 


pprogde Points to the PROGDETAILS structure that contains program infor- 
mation for the program being added to Desktop Manager. The PROGDETAILS 
structure has the following form: 


typedef struct _PROGDETAILS { 
ULONG Length; 
PROGTYPE progt; 
USHORT padl1[3]; 


PSZ pszTitle; 

PSZ pszExecutable; 
PSZ pszParameters; 
PSZ pszStartupDir; 
PSZ pszicon; 

PSZ pszEnvironment; 
SWP swpInitial; 


USHORT pad2[5]; 
} PROGDETAILS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hGroup Identifies the program group to which the program title is added. If 
this parameter is zero and the hini parameter is HINILUSERPROFILE, the pro- 
gram is added to the first group defined in Desktop Manager. 


Return Value The return value is the handle for the added program if the function is successful 
or NULL if an error occurs. 


Errors . Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_DUPLICATE_TITLE 
PMERR_GROUP_PROTECTED 
PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_PROGRAM_CATEGORY 
PMERR_INVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX | 


See Also PrfCreateGroup, PrfOpenProfile, PrfQueryDefinition, PrfQueryProgramTitles, 
WinAddProgram 
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PrfChangeProgram | New 
BOOL PrfChangeProgram( hini, hprog, pprogde) 

HINI hini; /« initialization-file handle »/ 

HPROGRAM hprog; /« program handle »/ 


PPROGDETAILS pprogde; /» address of structure with replacement info. «/ 


The PrfChangeProgram function changes the information stored in Desktop 
Manager about a program or group. 


Parameters hini Identifies the file that contains the program or group information to 
change. This parameter can be an initialization-file handle obtained by using the 
PrfOpenProfile function, or it can be the value HINILUSERPROFILE, specify- 
ing the user-profile file. 


hprog Identifies the program or group whose information is to change. If this 
parameter is a group handle, only the progt and pszTitle fields can be changed. 


pprogde Points to the PROGDETAILS structure that contains the new pro- 
gram information. The PROGDETAILS structure has the following form: 


i sain struct _PROGDETAILS { 
NG Length; 
PROGTYBE progt; 
USHORT padi[3]; 


PSZ pszTitle; 

PSZ pszExecutable; 

PSZ pszParameters; 
PSZ pszStartupDir; 

PSZ pszicon; 

PSZ pszEnvironment; 
SWP swpInitial; 


USHORT pad2[5]; 
} PROGDETAILS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_DUPLICATE_TITLE 
PMERR_GROUP_PROTECTED 
PMERR_LINVALID_PROGRAM_CATEGORY 
PMERR_INVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_IN_IDX 
PMERR_UNKNOWN_APIPKT 


Comments Typically, an application calls PrfQueryDefinition to retrieve current information 
about the function, changes the returned structure, and calls PrfChangeProgram 
to change the program information. 


You cannot change the program information for any program in a protected 
group. You can change only the visibility and the protected state. 


See Also PrfCreateGroup, PrfOpenProfile, PrfQueryDefinition 


mM PrfCloseProfile 
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New 


BOOL PrfCloseProfile ( hini) 
HINI hini; /« initialization-file handle «/ 


Parameters 


Return Value 


The PrfCloseProfile function closes a profile file opened by the PrfOpenProfile 
function. 


hini Identifies the profile file to close. The file must have been previously 
opened by using the PrfOpenProfile function. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be the 
following: 
PMERR_INVALID_INI_LFILE_LHANDLE 
See Also PrfOpenProfile 
mM PrfCreateGroup New 


HPROGRAM PrfCreateGroup( hini, pszTitle, fsVisible) 


HINE ini; 
PSZ pszTitle; 
UCHAR fsvVisible; 


Parameters 


/« initialization-file handle «/ 
/« pointer to group title »/ 
/« visibility flag »/ 


The PrfCreateGroup function creates a new program-group entry in Desktop 
Manager. If the program group already exists, this function returns a handle to 
that group. 


hini Identifies the file to which the new group is added. This parameter can be 
an initialization-file handle obtained by using the PrfOpenProfile function, or it 
can be the value HINILUSERPROFILE, specifying the user-profile file. 


pszTitle Points to the title of the new group. The maximum string size is 
defined by the MAXNAMEL constant (defined in the MS OS/2 include files). 
Strings that exceed this limit are truncated to MAXNAMEL characters. Leading 
and trailing blanks are removed. The string must contain at least one nonblank 
character and cannot contain a backslash (\). 


fsVisible Specifies the visibility of the new group. This flag can be a combina- 
tion of the following values: 


Value Meaning 

SHE_VISIBLE The group is visible. 

SHE_IN VISIBLE The group is invisible and cannot be viewed. 
SHE_UNPROTECTED The group is unprotected. 
SHE_PROTECTED The group is protected. Programs cannot be 


added or deleted from the group. 


This flag can also be set or reset by using the PrfChangeProgram function. 


Return Value 


Errors 


Comments 


See Also 
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The return value is the group handle for the group if the function is successful or 
NULL if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


The new program group is empty when created. Use the PrfAddProgram func- 
tion to add program entries to the group. 

The PrfCreateGroup function replaces the WinCreateGroup function used in 
MS OS/2, version 1.1. 


PrfAddProgram, PrfChangeProgram, WinCreateGroup 


PrfDestroyGroup New 
BOOL PrfDestroyGroup( hini, hGroup) 


HINI hini; /« initialization-file handle «/ 

HPROGRAM /AGroup; /« group handle a/ 
The PrfDestroyGroup function removes a group and all program information 
contained within that group from Desktop Manager. 

Parameters | hini Identifies the file that contains the group to remove. This parameter can 


Return Value 


Errors 


Comments 


See Also 


be an initialization-file handle obtained by using the PrfOpenProfile function, or 
it can be the value HINILUSERPROFILE, specifying the user-profile file. 


hGroup Identifies the group to be removed from Desktop Manager. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_GROUP_PROTECTED 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_TARGET_HANDLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


You cannot remove a group that is protected. You can remove a group that con- 
tains programs. 


PrfCreateGroup, PrfOpenProfile 


m@ PrfOpenProfile 


HINI PrfOpenProfile ( 
HAB hab; 
PSZ pszProfileName; 


Parameters 


Return Value 
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New 


hab, pszProfileName) 
/« anchor-block handle — »/ 
/« pointer to profile name «/ 


The PrfOpenProfile function opens a profile file. If the profile file does not 
already exist, this function creates it. This function cannot be used to open the 
user-profile or system-profile files. 


hab Identifies the anchor block. 


pszProfileName Points to the null-terminated string that contains the fully 
qualified filename of the profile file. If no path information is included, the 
default directory for the application is used. While not required, it is recom- 
mended that the extension .ini be used. 


The return value is a handle to the profile file if the function is successful or 
NULL if an error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 
PMERR_CALL_NOT_EXECUTED 
PMERR_INVALID_DIRECTORY 
See Also PrfCloseProfile 
@ PrfQueryDefinition New 
ULONG PrfQueryDefinition( hini, hprog, pprogde, cbBuf) 
HINI Aini; /« initialization-file handle x/ 
HPROGRAM hprog; /« program handle »/ 


PPROGDETAILS pprogde; /« address of structure for program info. »/ 


ULONG cbBuf; 


Parameters 


/« length of buffer for program info. «/ 


The PrfQueryDefinition function retrieves information about a program or pro- 
gram group. 


hini Identifies the file that contains the program information to retrieve. This 
parameter can be an initialization-file handle obtained by using the 
PrfOpenProfile function, or it can be the value HINILUSERPROFILE, specify- 
ing the user-profile file. . 


hprog Identifies the program or group for which information is to be 
retrieved. 


pprogde Points to the buffer that receives the program or group information. 
This buffer is formatted as a PROGDETAILS structure, followed by various 
strings pointed to by the fields within the PROGDETAILS structure. This buffer 
must be large enough for both the structure and all strings returned by this func- 
tion. 
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Return Value 


Errors 


Comments 


Example 


See Also 


The PROGDETAILS structure has the following form: 


typedef struct _PROGDETAILS { 
ULONG Length; 
PROGTYPE progt; 
USHORT padi([3]; 


PSZ pszTitle; 

PSZ pszExecutable; 

PSZ pszParameters; 

PSZ pszStartupDir; 

PSZ pszicon; 

PSZ pszEnvironment; 


SWP swpInitial; 
USHORT pad2[5]; 
} PROGDETAILS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbBuf Specifies the size (in bytes) of the buffer pointed to by the pprogde 
parameter. If this parameter is zero, only the length of the data is returned and 
the PROGDETAILS structure is not filled in. 


The return value is the number of bytes copied to the buffer pointed to by the 
pprogde parameter if the function is successful or zero if an error occurs. If the 
cbBuf parameter is zero, the return value is the size (in bytes) of the required 
buffer pointed to by the pprogde parameter. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_BUFFER_TOO_SMALL 
PMERR_INVALID_PARM 
PMERR_INVALID_PIB 
PMERR_INVALID_PROGRAM_HANDLE 
PMERR_INVALID_GROUP_HANDLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


If the hprog parameter is a group handle, only the progt and pszTitle fields in 
the PROGDETAILS structure pointed to by pprogde are filled in. 


The PrfQueryDefinition function replaces the WinQueryDefintion function used 
in MS OS/2, version 1.1. 


This example calls PrfQueryDefinition to determine the size of the buffer needed 
to retrieve all of the information. It then calls DosAllocSeg to allocate the 
memory and calls PrfQueryDefinition again to retrieve all of the program infor- 
mation. 

SEL sel; 


ULONG cb; 
PPROGDETAILS pprogde; 


/* First find the size of the buffer needed. */ 
cb = PrfQueryDefinition(HINILUSERPROFILE, hprog, NULL, OL); 
DosAllocSeg(cb, &sel, SEG_NONSHARED) ; 


pprogde = MAKEP(sel, 0); 
cb = PrfQueryDefinition(HINI_LUSERPROFILE, hprog, pprogde, cb); 


PrfAddProgram, PrfOpenProfile, WinQueryDefinition 


mM PrfQueryProfile 
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New 


BOOL PrfQueryProfile ( hab, pprfprofile) 


HAB hab; 


/» anchor-block handle s/ 


PPRFPROFILE pprfprofile; /« address of structure for profile data »/ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The PrfQueryProfile function retrieves the fully qualified filenames of the two 
MS OS/2 profile (initialization) files. 
hab Identifies the anchor block. 


pprfstruct Points to the PRFPROFILE structure that receives information 
about the profile filenames. The PRFPROFILE structure has the following form: 


typedef struct _PREPROFILE { 
ULONG cchUserName; 


PSZ pszUserName; 
ULONG cchSysName; 
PSZ pszSysName; 


} PREPROFILE; 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. ; 


If either length field (ecchUserName or cchSysName) of the PRFPROFILE struc- 
ture is set to zero when calling this function, the length field is set to the number 
of bytes required to hold the corresponding filename, and that filename field is 
not filled in. 


This example calls PrfQueryProfile to retrieve the size of the filenames, allocates 
the memory needed for each string, and calls PrfQueryProfile again to retrieve 
the filenames. 


PRFPROFILE prfpro; 
SEL selUser; 
SEL selSys; 


prfpro.cchUserName = OL; 

prfpro.cchSysName = OL; 

PrfQueryProfile(hab, &prfpro); /* gets size of filenames */ 
DosAllocSeg(prfpro.cchUserName, &selUser, SEG_NONSHARED) ; 
DosAllocSeg(prfpro.cchSysName, &selSys, SEG_NONSHARED) ; 
prfpro.pszUserName = MAKEP(selUser, 0); /* initializes pointers s/ 
prfpro.pszSysName = MAKEP(selSys, 0); 

PrfQueryProfile(hab, &prfpro); 


PrfReset 
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HINI hinis 

PSZ pszAppName; 
PSZ pszKeyName; 
PVOID pvBuf; 


mM PrfQueryProfileData New 
BOOL PrfQueryProfileData( hini, pszAppName, pszKeyName, pvBuf, DobBuf) 
/ initialization-file handle s/ 
/« pointer to application name «/ 
/« pointer to keyname »/ 
/« pointer to buffer »/ 
/« buffer length »/ 


PULONG pcbBuf; 


Parameters 


Return Value 


Errors 


Comments 


The PrfQueryProfileData function retrieves binary data from the profile file. The 
location of the data is determined by the application name and keyname that are 
passed to the function. 


hini Identifies the file to query. This parameter can be a file handle obtained 
with PrfOpenProfile or one of the following values: 


Value Meaning 

HINI_PROFILE Search the user profile, and if no matching 
entries are found, search the system profile. 

HINI_USERPROFILE Search only the user profile. 


HINI_LSYSTEMPROFILE Search only the system profile. 


pszAppName Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing character. The application name is case-sensitive. If pszAppName is NULL, 
a list of all application names in the profile specified by the hini parameter is 
returned. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating char- 
acter. The keyname is case-sensitive. If pszKeyName is NULL, all keynames in 
the profile specified by the hini parameter are enumerated. 


pvBuf Points to the buffer that receives the data. 


pcbBuf Points to the variable that contains the size of the buffer pointed to by 
the pyBuf parameter. When the function returns, this variable contains the actual 
number of bytes placed in the buffer. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_PARM 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 


When a NULL is used in pszKeyName, if the application name specified by 
pszAppName is not found, PrfQueryProfileData returns FALSE. 


The size of the data can be determined by calling the PrfQueryProfileSize func- 
tion. In cases where pvBuf points to a list of values, the value returned by 
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PrfQueryProfileSize will include a NULL byte at the end of the list, used as a 
terminator. 


See Also PrfQueryProfileSize, PrfWriteProfileData, WinQueryProfileData 
PrfQueryProfileInt New 
SHORT PrfQueryProfileInt( hini, pszAppName, pszKeyName, SError) 

HINI hini; /« initialization-file handle »/ 

PSZ pszAppName; /« pointer to application name _ »/ 

PSZ pszKeyName; /« pointer to keyname »/ 


SHORT sError, 


Parameters 


Return Value 


Errors 


Comments 


See Also 


/» value returned if keyname not found »«/ 
The PrfQueryProfileInt function retrieves an integer from the profile file. 


hini Identifies the file to query. This parameter can be a file handle obtained 
with PrfOpenProfile or one of the following values: 


Value Meaning 


HINI_USERPROFILE Search only the user profile. 
HINI_LSYSTEMPROFILE Search only the system profile. 


pszAppName Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing character. The application name is case-sensitive. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating char- 
acter. The keyname is case-sensitive. 


sError Specifies the error value returned if the keyname specified by the 
pszKeyName parameter cannot be found. 


The return value is the integer representation of the text string. If the keyname 
cannot be found, the return value is the error value specified by the sError 
parameter. 


Use the WinGetLastError function to retrieve the error value, which may be one 


of the following: 


PMERR_INVALID_PARM 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_IN_IDX 


The location of the integer is determined by the application name and keyname 
passed to this function. The PrfWriteProfileString function must have been used 
previously to store the integer as a string. For example, a string stored as “123” 
would be returned as the integer 123. The string may contain a leading minus 
sign if the number is negative. 


PrfQueryProfileData, PrfWriteProfileString, WinQueryProfileInt 


HINI ini; 
PSZ pszAppName; 
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PrfQueryProfileSize New 
BOOL PrfQueryProfileSize ( hini, pszAppName, pszKeyName, pcb) 

/« initialization-file handle »/ 

/« pointer to application name »/ 

/» pointer to keyname »/ 


PSZ pszKeyName; 
PULONG pcb; 


Parameters 


Return Value 


Errors 


Comments 


See Also 


/« pointer to variable with data length »/ 


The PrfQueryProfileSize function retrieves the size of the data stored at a 
specified location in the profile file. 


hini Identifies the file to query. This parameter can be a file handle or one of 
the following values: 


Value Meaning 

HINI_PROFILE Search the user profile, and if no matching 
entries are found, search the system profile. 

HINI_LUSERPROFILE Search the user profile only. 


HINI_SYSTEMPROFILE Search the system profile only. 


pszAppName Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing character. The application name is case-sensitive. If pszAppName is NULL, 
the length returned in the variable pointed to by the pcb parameter is the length 
required to contain a list of all application names for the pszKeyName parame- 
ter. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating-char- 
acter. The keyname is case-sensitive. If pstKeyName is NULL, the length 
returned in the variable pointed to by the pcb parameter is the length required to 
contain a list of all keynames. 


pcb Points to the variable that receives the length of the data. If an error 
occurs, the length is not returned. 


The return value is TRUE if the function is successful. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_PARM 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 


The location of the data stored in the profile file is determined by the application 
name and keyname passed to this function. This function is typically called to 
determine how much memory to allocate before calling PrfQueryProfileData. 


The count returned by this function will be 1 greater than that returned by 
PrfQueryProfileData or PrfQueryProfileString in cases where these functions 
will return a list. This is due to an additional NULL character used as a termina- 
tor for the entire list. 


PrfQueryProfileData, PrfQueryProfileString, WinQueryProfileSize 


HINI hini; 

PSZ pszAppName; 
PSZ pszKeyName; 
PSZ pszError; 
PSZ pszBuf; 
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H@ PrfQueryProfileString New 
ULONG PrfQueryProfileString( hini, pszAppName, pszKeyName, pszError, pszBuf, cchBuf) 
/« initialization-file handle «/ : 
/« pointer to application name +/ 
/» pointer to keyname »/ 
/« pointer to default string »/ 
/» pointer to buffer for string = «/ 
/» buffer size »/ 


ULONG cchBuf; 


Parameters 


Return Value 


Errors 


Comments 


The PrfQueryProfileString function retrieves a string from the profile file. The 
location of the string is determined by the application name and keyname passed 
to this function. 


hini Identifies the file to query. This parameter can be a file handle or one of 
the following values: 


Value Meaning 

HINI_PROFILE Search the user profile, and if no matching 
entries are found, search the system profile. 

HINI_USERPROFILE Search only the user profile. 


HINI_LSYSTEMPROFILE Search only the system profile. 


pszAppName Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing character. The application name is case-sensitive. If pszAppName is NULL, 
a list of all application names in the profile specified by the hini parameter is 
returned. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating char- 
acter. The keyname is case-sensitive. If pszKeyName is NULL, all keynames in 
the profile specified by the hini parameter are enumerated. 


pszError Points to the null-terminated string placed in the buffer pointed to by 
pszBuf if the keyname is not found. 


pszBuf Points to the buffer that receives the null-terminated string. 


cchBuf Specifies the length of the buffer pointed to by the pszBuf parameter. 
If the string retrieved is longer than this value, it is truncated. 


The return value is the number of characters in the buffer pointed to by pszBuf, 
or zero if an error occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_PARM 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 


When NULL is used in pszKeyName and the application name specified by 
pszAppName is not found, PrfQueryProfileString returns FALSE. 
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See Also 


Application data should be stored in the user profile or an application-specific 
profile. The system profile should be used only for system data. 


PrfWriteProfileString, WinQueryProfileString 


PrfQueryProgramCategory New 
PROGCATEGORY PrfQueryProgramCategory( hini, pszProgramName) 


HIN] hini; 


/» initialization-file handle —«/ 


PSZ pszProgramName; /» pointer to program name «/ 


Parameters 


Return Value 


Errors 


Comments 


See Also 


The PrfQueryProgramCategory function retrieves the type (category) of a 
specified program. 


hini Identifies the file to search for program information (if the program type’ 
cannot be determined by searching the header of the executable file). This 
parameter can be an initialization-file handle obtained by using the PrfOpen- 
Profile function, or it can be the value HINL.USERPROFILE, specifying the 
user-profile file. 


pszProgramName Points to the null-terminated string that contains the name 
of the executable file for which the type is to be returned. If the string appears 
to be a fully qualified path [(that is, it contains a colon (:) in the second position 
and/or contains a backslash (\)], the file is searched for in the indicated direc- 
tory on the indicated drive. If neither of these conditions is true and the file is 
not in the current directory, each drive and directory specified in the path 
defined in the current program’s environment is searched. The default extension 
for an executable file is .eve, although any extension is acceptable. 


The return value is the program category if the function is successful or zero if 
an error occurs. The program type can be one of the following values: 


sa aL eee eee 
PROG_FULLSCREEN Program runs only in a full-screen session. 
PROG_WINDOWABLEVIO Program runs in a VIO window. 
PROG_PM Program is a Presentation Manager appli- 
cation. 
PROG_REAL Program is a real-mode (DOS) application. 
PROG_DLL Program is a dynamic-link module. 


Use the WinGetLastError function to retrieve the error value, which may be the 
following: 


PMERR_DOS_ERROR 


The PrfQueryProgramCategory function first calls the DosQAppType function. 
If the program type cannot be determined from this call, the profile specified by 
the hini parameter is searched. 


Because this function calls DosQAppType, the program type returned may not 
be the same type the user specified for the program in Desktop Manager. 


DosQAppType, PrfQueryDefinition 


HINI hinis 
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M@ PrfQueryProgramHandle New 
ULONG PrfQueryProgramHandle ( hini, pszExeName, phpga, cb, pcHandles) 
/s initialization-file handle «/ 
/« pointer to executable-file name »/ 


PSZ pszExeName; 


PHPROGARRAY phpga; /»« address of structure for program handles »/ 


ULONG cb; /« buffer size »/ 

PULONG pcHandles; /» pointer to variable for number of handles «/ 
The PrfQueryProgramHandle function retrieves the program handles that match 
the name of a specified executable file. 

Parameters hini Identifies the file that contains the program information to retrieve. This 


Return Value 


Errors 


Comments 


See Also 


parameter can be an initialization-file handle obtained by using PrfOpenProfile 
function, or it can be the value HINILUSERPROFILE, specifying the user- 
profile file. 


pszExeName _ Points to the fully qualified path [that is, it contains a colon (:) 
in the second position and/or contains a backslash (\)] of the executable file. 


phpga Points to the HPROGARRAY structure that receives the program han- 
dles, one for each match found. The HPROGARRAY structure has the following 
form: 

typedef struct _HPROGARRAY { 


HPROGRAM ahprog[1]; 
} HPROGARRAY; 


cb Specifies the size (in bytes) of the buffer pointed to by the phpga parame- 
ter. The buffer must be large enough to hold all the program handles retrieved. 


pcHandles Points to the variable that receives the number of program handles 
placed in the structure pointed to by the phpga parameter. If this value is zero 
when the function returns, the buffer size specified by the cb parameter is 
insufficient to hold all the program handles or an error occurred. 


The return value is the size (in bytes) of the required buffer if the function is 
successful. Otherwise, it is zero, indicating an error occurred or the filename 
was not found. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_INI_LFILE_HANDLE 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR._MEMORY_ALLOCATION_ERR 


Typically, an application calls this function twice. The first time, the cb parame- 
ter is set to zero and the return valuc is used to determine how much memory 
must be allocated to hold the program handles. The second call actually retrieves 
the program handles. . 


PrfOpenProfile 
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PrfQueryProgramfitles New 
ULONG PrfQueryProgramTitles( hini, hGroup, paprogti, cbBuf, pcTitles ) 

HINI hinis . /« initialization-file handle «/ 

HPROGRAM AGroup; -/» handle of group »/ 

PPROGTITLE paprogti; /» array of structures with program info. »«/ 

ULONG cbBuf; /» length of buffer for array of structures »/ 

PULONG pcTitles; /» pointer to variable for titles »/ 


The PrfQueryProgramTitles function retrieves information about programs 
within a specified group in Desktop Manager. 


Parameters hini Identifies the file that contains the program information to retrieve. This 
parameter can be an initialization-file handle obtained by using the PrfOpen- 
Profile function, or it can be the value HINILUSERPROFILE, specifying the 
user-profile file. 


hGroup Identifies the group or program for which information is to be 
returned. This handle can be SGH_ROOT to retrieve information about all the 
groups in Desktop Manager. 


paprogti Points to the buffer that receives an array of one or more 
PROGTITLE structures followed by the strings pointed to within the structures. 
The PROGTITLE structure has the following form: 
typedef struct _PROGTITLE { 

HPROGRAM hprog; 

PROGTYPE progt; 

USHORT padi [3]; 


PSZ pszTitle; 
} PROGTITLE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbBuf Specifies the total length (in bytes) of the buffer pointed to by the 
paprogti parameter. 


pcTitles Points to the variable that receives the count of titles. 


Return Value The return value is the size of the required buffer if the function is successful or 
zero if an error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_BUFFER_TOO_SMALL 
PMERR_INI_LFILE_CORRUPT 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_PARM 
PMERR_LINVALID_TARGET_HANDLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NO_ENTRIES_IN_GROUP 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 
PMERR_NO_PROGRAM_FOUND 


Comments Typically an application calls this function twice. The first time, the cbBuf 
parameter is set to zero. The return value is used to allocate a sufficient buffer. 
Then, the application calls the function again to retrieve the program titles. 
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If a program handle is specified for the hGroup parameter, the information for 
only that instance of the program is returned. 


See Also PrfAddProgram, PrfOpenProfile, WinQueryProgramTitles 


PrfRemoveProgram New 


BOOL PrfRemoveProgram( hini, hProgram) 
HINI Aini: /« initialization-file handle »/ 
HPROGRAM hProgram; /« program handle »/ 


The PrfRemoveProgram function removes a program from Desktop Manager. 


Parameters hini Identifies the file that contains the program information to remove. This 
parameter can be an initialization-file handle obtained by using the PrfOpen- 
Profile function, or it can be the value HINI_LUSERPROFILE, specifying the 
user-profile file. 


hProgram Identifies the program to remove from Desktop Manager. This 
parameter cannot be a group handle. 


Return Value — The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_GROUP_PROTECTED 
PMERR_INVALID_INI_LFILE_LHANDLE 
PMERR_INVALID_PIB 
PMERR_INVALID_PROGRAM_HANDLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 


Comments You can remove a program from a group, even if the program is currently run- 
ning. Only the program information in the group is removed—the program itself 
is not affected. 


See Also PrfDestroyGroup, PrfOpenProfile 


PrfReset New 
BOOL PrfReset( hab, pprfpro) 

HAB hab; /« anchor-block handle »/ 

pprfpro pprfpro; /« address of structure with profile data «/ 


The PrfReset function resets Presentation Manager by rereading the initialization 
files. This function can change which initialization files are to be used by the sys- 
tem. 


Parameters hab Identifies the anchor block. 
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Return Value 


Errors 


Comments 


See Also 


pprfpro Points to the PRFPROFILE structure that contains the filenames of 
the initialization files. The PRFPROFILE structure has the following form: 
typedef struct _PREPROFILE { 

ULONG' cchUserName; 

PSZ pszUserName; 

ULONG cchSysName; 


PSZ pszSysName; 
} PREPROFILE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_CALL_NOT_EXECUTED 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_MEMORY_SHARE 
PMERR_OPEN_QUEUE 
PMERR_WRITE_QUEUE 


The system is reset by rereading the initialization files that are specified in the 
PRFPROFILE structure. Both initialization files must be specified before calling 
this function. 


If the path is not included as part of the initialization-file names, the current 
directory is used. 


The PrfReset function modifies the PRFPROFILE structure passed to it. Before 
you can use this structure again, you must reinitialize its values. 


PrfQueryProfile 


PrfWriteProfileData New 


BOOL PrfWriteProfileData( hini, pszAppName, pszKeyName, pchBinaryData, cchData) 


HINI Aini; 
PSZ pszAppName; 
PSZ pszKeyName; 


/x initialization-file handle a/ 
/« pointer to application name «/ 
/x pointer to keyname »/ 


PVOID pchBinaryData; /« pointer to data in profile file «/ 


ULONG cchData; 


/« data length »/ 


The PrfWriteProfileData function places binary data in the specified profile file. 
The location of the data is determined by the application name and keyname 
passed to the function. This data can then be retrieved by using the PrfQuery- 
ProfileData function, with the application name and keyname specified in the 
pszAppName and pszKeyName parameters of the PrfWriteProfileData function. 


Parameters 


Return Value 
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hini Identifies the file in which to place the binary data. This parameter can be 
a file handle or one of the following values: 


Value Meaning 


HINI_USERPROFILE Specifies the user profile. 
HINI_LSYSTEMPROFILE Specifies the system profile. 


pszAppName_ Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing charactér. The application name is case-sensitive. If no application field in 
the profile file matches pszAppName, a new application field is created. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating char- 
acter. If this parameter is NULL, all keynames and their data are deleted. The 
keyname is case-sénsitive. If no keyname matches pszKeyName, a new keyname 
field is created. If the keyname already exists, the existing value is overwritten. 


pchBinaryData _ Poitits to the binary data placed in the profile file. There is no 
explicit terminating character. If this parameter is NULL, the previous value 
associated with the pszKeyName parameter is deleted; otherwise, the data string 
becomes the value, even if its length is zero. The data should not exceed 64K. 


cchData Specifies the size (in bytes) of the pchBinaryData parameter. 


The return value is TRUE if the function is successful or FALSE if an error 


occurs. If the profile file exists but is somehow corrupted, this function returns 
FALSE. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 
PMERR_INVALID_PARM 
PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
Comments The application must know the size of the stored data when it calls 
PrfQueryProfileData to retrieve the data. 
See Also PrfQueryProfileData, WinWriteProfileData 
PrfWriteProfileString New 
BOOL PrfWriteProfileString( hini, pszAppName, pszKeyName, pszString) 
HINI hinis /« initialization-file handle »/ 
PSZ pszAppName; /« pointer to application name »/ 
PSZ pszKeyName; /« pointer to keyname »/ 
PSZ pszString; /« pointer to string to write »/ 


The PrfWriteProfileString function places an ASCII string in the profile file. 
The location of the string is determined by the application name and keyname 
passed to the function. The string can then be retrieved by using the PrfQuery- 
ProfileString function, specifying the same application name and keyname given 
in the pszAppName and pszKeyName parameters of PrfWriteProfileString. 
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Parameters 


Return Value 


Errors 


Comments 


See Also 


hini Identifies the file to query. This parameter can be a file handle or one of 
the following values: 


Value Meaning 


HINI_USERPROFILE Specifies the user profile. 
HINI_SYSTEMPROFILE | Specifies the system profile. 


pszAppName Points to the null-terminated string that contains the application 
name. The string must be less than 1024 bytes long, including the null terminat- 
ing character. The application name is case-sensitive. If no application field in 
the profile file matches pszAppName, a new application field is created. 


pszKeyName Points to the null-terminated string that contains the keyname. 
The string must be less than 1024 bytes long, including the null terminating char- 
acter. If pszKeyName is NULL, all keynames and their data are deleted. The 
keyname is case-sensitive. If no keyname matches pszKeyName, a new keyname 
field is created. If the keyname already exists, the existing value is overwritten. 


pszString Points to the null-terminated ASCII string placed in the profile file. 
If pszString is NULL, the previous value associated with pszKeyName is deleted; 
otherwise, the ASCII string becomes the value, even if its length is zero. The 
string should not exceed 64K. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_PARM 

- PMERR_MEMORY_ALLOC 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 


User application data should be stored in either the user profile or an application 
specific profile. The system profile should be used only for system data, such as 
spooler information. 


PrfQueryProfileString, WinWriteProfileString 


SBM_SETTHUMBSIZE New 


Parameters 


Return Value 


SBM_SETTHUMBSIZE 
mpl = MPFROM2SHORT((USHORT) cVisible, (USHORT) cTotal); /* items */ 
mp2 = OL; /* not used, must be zero */ 


An application sends an SSM_SETTHUMBSIZE message to set the size of the 
slider in the scroll bar. 


cVisible Low word of mp1. Specifies the number of visible items. 
cTotal High word of mp]. Specifies the total number of items. 


The return value is always TRUE. 
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Comments The SBM_SETTHUMBSIZE message is usually sent when the scroll bar is ini- 
tialized or when the client window changes size. MS OS/2 uses the two parame- 
ters to calculate the percentage of data visible and thus the percentage of the 
scroll bar that the slider should occupy. 

See Also SBM_QUERYPOS, SBM_QUERYRANGE, SBM_SETPOS 

SCR_ALLOCLDT New 

USHORT DosDeviOCtl( pse/, pvAddrinfo, 0x0070, 0x0003, hDevice) 

PSEL psel; /» pointer to LDT selector »/ 

PVOID pvAddrinfo; /« pointer to structure with address info »/ 

HFILE hDevice; /» device handle af 


Parameters 


Return Value 


The SCR_ALLOCLDT function allocates a logical descriptor table (LDT) selec- 
tor for an area of memory. 


psel Points to the logical descriptor table selector for the memory area 
specified by the LDTADDRINFO structure. 


pvAddrInfo Points to the LDTADDRINFO structure that contains the address 
and size of memory for which a selector is requested. 


The LDTADDRINFO structure has the following form: 
typedef struct _LDTADDRINEFO { 
PULONG pulPhysAddr; 
USHORT cb; 
} LDTADDRINEO; 
For a full description, see Chapter 4, “Types, Macros, Structures.” 
hDevice Identifies the screen device that receives the device-control function. 
This handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or the error value 
ERROR_I24_INVALID_PARAMETER if an error occurs. 


Comments Read/Write access is granted to data areas completely contained in the address 
range 0xA0000 through OxBFFFF. Read-only access is granted to data areas out- 
side this range, but inside the range 0x00000 through OxFFFFF. Attempts to 
access any address outside this range results in an error. 

See Also SCR_ALLOCLDTOFF, SCR_.DEALLOCLDT 

SCR_ALLOCLDTOFF New 


USHORT DosDevlOCtl( ppv, pvAddrinfo, 0x0075, 0x0003, hDevice) 


PVOID FAR * ppv; 
PVOID pvAddrinfo; 


HFILE hDevice; 


/« pointer to variable to receive selector:offset «/ 
/« pointer to structure with address info »/ 
/« device handle »/ 


The SCR_ALLOCLDTOFF function allocates a logical descriptor table (LDT) 
selector and offset for an area of memory. 


Parameters 


Return Value 
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ppv Points to the variable that receives the allocated selector and offset. 


pvAddrinfo Points to the LDTADDRINFO structure that contains the address 
and size of memory for which a selector is requested. 


The LDTADDRINFO structure has the following form: 
typedef struct _LDTADDRINEFO { 
PULONG pulPhysAddr; 
USHORT cb; 
} LDTADDRINEFO; 
For a full description, see Chapter 4, “Types, Macros, Structures.” 
hDevice Identifies the screen device that receives the device-control function. 
This handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or the error 
ERROR_I24_INVALID_PARAMETER if an error occurs. 


Comments Read/Write access is granted to data areas completely contained in the address 
range 0xA0000 through OxBFFFF. Read-only access is granted to data areas out- 
side this range, but inside the range 0x00000 through OxFFFFF. Attempts to 
access any address outside this range results in an error. 

See Also SCR_ALLOCLDT, SCR_.DEALLOCLDT 

SCR_DEALLOCLDT New 


USHORT DosDeviOCtI( OL, pse/, 0x0071, 0x0003, hDevice) 


PSEL psel; 
HFILE ADevice; 


Parameters 


Return Value 


See Also 


/« pointer to LDT selector »/ 
/» device handle »/ 


The SCR_.DEALLOCLDT function deallocates a logical descriptor table 


(LDT) selector previously allocated by the SCR_ALLOCLDT or 
SCR_ALLOCLDTOFF function. 


psel Points to the logical descriptor table selector to be deallocated. 


hDevice Identifies the screen device that receives the device-control function. 
This handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or the error value 
ERROR_I24_INVALID_PARAMETER ig an error occurs. 


SCR_ALLOCLDT, SCR_ALLOCLDTOFF 
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—H TBM_TRACKMOVE New 


TBM_TRACKMOVE 
mpl = MPFROMSHORT (fs); 
mp2 = OL; 


/* tracking options a/ 
* not used, must be zero */ 


An application sends a TBM_TRACKMOVE message to a title-bar window con- 
trol to move its owner window. 


A WM_QUERYTRACKINFO message is first sent to the owner of the title-bar 
window control. If the return value is TRUE, the window is moved; otherwise, 
the operation terminates. , 


Parameters fs Low word of mp1. Specifies tracking options. This parameter can be a com- 
bination of the following values: 
Option Meaning 
TF_LEFT Tracks the left side of the rectangle. 
TF_TOP Tracks the top of the rectangle. 
TF_RIGHT Tracks the right of the rectangle. 
TF_BOTTOM Tracks the bottom of the rectangle. 
TF_MOVE Tracks all sides of the rectangle. 


Return Value 


See Also 


TF_POINTERPOS 


Repositions the pointer according to the other 
options specified. 


TF_LEFT Vertically centers the pointer at the left of the 
tracking rectangle. 

TF_TOP Horizontally centers the pointer at the top of the 
tracking rectangle. 

TF_RIGHT Vertically centers the pointer at the right of the 
tracking rectangle. 

TF_BOTTOM Horizontally centers the pointer at the bottom of 
the tracking rectangle. 

TF_MOVE Centers the pointer in the tracking rectangle. 

TF_GRID Restricts tracking to a predetermined grid. 


TF_STANDARD 


TF_ALINBOUNDARY 


TF_PARTINBOUNDARY 


The width, height, grid width, and grid height are 
all multiples of the border width and border height. 


Tracks so that no part of the tracking rectangle 
ever falls outside the bounding rectangle. 


Tracks so that the corresponding edge of the track- 
ing rectangle is kept within the opposite edge of 
the boundary rectangle. 


The return value is TRUE if the operation is successful or FALSE if an error 
occurs. 


WM_QUERYTRACKINFO 


VioCreatePS 


272 VioCreatePS 


Correction 


USHORT VioCreatePS( phvps, cRows, cColumns, fFormat, cAttrBytes, hvps) 


PHVPS phvps; 
SHORT cRows; 
SHORT cColumns; 
SHORT fFormat; 
SHORT cAttrBytes; 
HVPS hvps; 


Parameters 


Return Value 


See Also 


Corrections 


/« pointer to variable for presentation-space handle »«/ 


' /x height of presentation space »/ 
/x width of presentation space »/ 
/« format of attribute byte(s) »/ 
/x number of attributes. »/ 
/« presentation-space handle »/ 


The VioCreatePS function creates an advanced video-input-and-output (A VIO) 
presentation space, the size of which must not exceed 64K. To determine the 
size of the presentation space, multiply the cColumns, cRows, and cAttrBytes 
parameters as follows: cColumns x cRows x (cAttrBytes + 1). 


phvps Points to the variable that receives the presentation-space handle. You 
may use this handle in subsequent Vio functions. 


cRows Specifies the height (in character cells) of the presentation space. 
cColumns Specifies the width (in character cells) of the presentation space. 


fFormat Identifies the format of the attribute byte(s) in the presentation 
space. The content of the attribute bytes depends on the format. Currently, the 
only defined format is zero. If the format is zero, the attribute bytes have the fol- 
lowing meanings: 

Value Meaning 


FORMAT_CGA Specifies a CGA format of two attribute bytes. The first 
byte contains the character value. The second byte con- 
tains bit fields that specify the background and fore- 
ground colors. Blink and intensity fields are not sup- 
ported. 


-FORMAT_4BYTE Specifies an extended format of four attribute bytes. 
The first byte contains the character value. The second 
byte contains bit fields that specify the background and 
foreground colors. The third byte contains bit fields 
that specify the underscore, reverse video, the back- 
ground opacity, and the font identifier. The fourth byte 
is an extra byte to be used by programs. 


cAttrBytes Specifies the number of attribute bytes per character cell in the 
presentation space. This number may be 1 or 3. 


hvps Identifies the AVIO presentation space. This parameter must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


VioDestroyPS 


The presentation space must not exceed 64K, not 32K as previously docu- 
mented. 


—H VioGetBuf 
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Correction 


USHORT VioGetBuf( pu/LVB, pcbLVB, hvio) 


PULONG pulLvB; 
PUSHORT pcbLvB; 


HVIO hvio; 


Parameters 


Return Value 


Comments 


Example 


See Also 


Corrections 


/» pointer to variable for address of LVB +/ 
/« pointer to variable for length of LVB _»/ 
/« video handle »/ 


The VioGetBuf function retrieves the address of the logical video buffer (LVB) 
that contains the current character attributes for the text output of a process. 
The logical video buffer is available for text-mode screens only. 


A process can access and modify the contents of the logical video buffer at any 
time, even if the process is in the background. Changes made to the logical 
video buffer do not affect the physical screen until the process calls the 
VioShowBuf function. 


pulLVB Points to the variable that receives the address of the logical video 
buffer. 


pcbLVB Points to the variable that specifies the length (in bytes) of the logical 
video buffer. You can use the VioGetMode function to determine the dimen- 
sions of the buffer. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created using the 
VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_HANDLE 
If the process calling VioGetBuf is in the foreground, all VIO output calls are 
written.to both the physical display buffer and the logical video buffer. 


If the VioSetMode function is called following a call to VioGetBuf, the size of 
the logical video buffer is adjusted to correspond to the new mode. 


There is one logical video buffer per session (or presentation space, for an 
AVIO application). 


This example calls VioGetBuf to retrieve the address of the logical video buffer. 
It sets the character attributes in the buffer for foreground blinking by using the 
OR operator to set the high bit, then it calls the VioShowBuf function to display 
the character attributes: . 
PBYTE pbLVB; 
USHORT cbLVB, i; 
VioGetBuf((PULONG) &pbLVB, &cbLVB, 0); 
for (i = O; i < cbhLVB; i += 2) 

/* OR in the high bit to make it a blinking attribute */ 


*(pbLVB + 4 + 1) = *(pbLVB + i + 1) | Ox80; 
VioShowBuf (0, cbLVB, 0); /* displays buffer */ 


VioGetMode, VioGetPhysBuf, VioShowBuf 


This function is not a Family API function. 


The physical and logical video buffers are not always identical. 
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HZ VioGetConfig 


USHORT VioGetConfig( usConfigid, pvioin, hvio) 
USHORT usConfiglid; /« configuration ID 
PVIOCONFIGINFO pvioin; 


HVIO Avio; /« video handle 


Change 


»/ 


/« pointer to structure for configuration »/ 


»/ 


Parameters 


The VioGetConfig function retrieves the video-display configuration, which 
defines the type of display adapter, the type of display, and the amount of video 
memory available in the current, primary, or secondary display. 


The VioGetConfig function is a family API function. 


usConfigId Specifies the display adapter to retrieve the configuration for. This 
parameter can be one of the following values: 


Value Meaning 


VIO_CONFIG_CURRENT 
VIO_CONFIG_PRIMARY 
VIO_CONFIG_SECONDARY 


The current display adapter 
The primary display adapter 
The secondary display adapter 


Return Value 


Comments 


pvioin Points to the VIOCONFIGINFO structure that receives the display 
configuration for the primary display adapter. The VIOCONFIGINFO structure 
has the following form: 


typedef struct _VIOCONFIGINFO { 
USHORT cb; 
USHORT adapter; 
USHORT display; 

' ULONG cbhMemory; 
USHORT config; 
USHORT dd_ver; 
USHORT flags; 

ULONG hwbuf; 
ULONG maxfullbuf; 
ULONG maxpartbuf; 
USHORT adaptptr; 
USHORT dispptr; 
USHORT cwadapt; 
USHORT adaptdata([1]; 
USHORT cwdisp; 
USHORT dispdata[1]; 
} VIOCONFIGINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created using the 
VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_LENGTH 
ERROR_VIO_LINVALID_PARMS 


MS OS/2 derives the values for the adapter and display fields of the 
VIOCONFIGINFO structure for the display configuration by using various tests, 
including checking the switch settings on the card. 


VioGetMode 275 


Example This example calls VioGetConfig to determine whether the primary display type 
is an enhanced color display: 
VIOCONFIGINFO vioinConfig; 
vioinConfig.cb = sizeof (vioinConfig) ; /* structure length */ 
VioGetConfig(VIO_CONFIG_PRIMARY, 
&vioinConfig, /7* configuration data od 
0); /* video handle 
if (vioinConfig.display == DISPLAY_EGA) 
VioWrtTTY ("Enhanced color displayO, 24, 0); 
See Also VioGetMode, VioGetState 
Changes The first parameter changed from usReserved to usConfigId, allowing you to 
specify which display adapter to get the configuration information from. 
The VIOCONFIGINFO structure pointed to by the pvioin parameter contains 
additional fields when used in MS OS/2, version 1.2. 
VioGetMode Change 


USHORT VioGetMode( pviomi, hvio) 
PVIOMODEINFO pviomi; /» pointer to structure for screen-mode information »/ 
HVIO hAvio; /« video handle »/ 


The VioGetMode function retrieves the current screen mode. The screen mode 
defines the display mode (text or graphics), the number of colors being used 
(2, 4, or 16), and the width and height of the screen in both character cells and 
pels. 


The VioGetMode function is a family API function. 


pviomi Points to the VIOMODEINFO structure that receives the screen-mode 
information. The VIOMODEINFO structure has the following form: 


typedef struct _VIOMODEINFO { 
USHORT cb; 
UCHAR fbType; 
UCHAR color; 


Parameters 


Return Value 


USHORT 
USHORT 
USHORT 
USHORT 


col; 
row; 
hres; 
vres; 


UCHAR attribfmt; 
UCHAR attribcount; 
ULONG pdbaddr; 
ULONG pdblen; 
ULONG fullbufsz; 
ULONG partbufsz; 
ULONG edaaddr; 
} VIOMODEINEFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hvio This parameter must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_INVALID_LENGTH 
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Comments 


Example 


See Also 


Changes 


Corrections 


VioGetState 


The hvio parameter can be only NULL. This function cannot be used by an 
advanced video-input-and-output application. 


This example calls VioGetMode to retrieve the mode information for the screen: 
VIOMODEINFO viomi; 


viomi.cb = sizeof (viomi) ; 
VioGetMode (&viomi, 0); 
if (viomi.fbType == 0) 


VioWrtTTY ("Monochrome display\n\r", 20, 0); 
VioCreatePS, VioGetState, VioSetMode 


The VIOMODEINFO structure pointed to by the pviomi parameter contains 
several additional fields when used in MS OS/2,version 1.2. 


The hvio parameter can be only NULL. This function cannot be used by an 
advanced video-input-and-output application. 


Change 


USHORT VioGetState ( pvoidState, hvio) 


PVOID pvoidState; 


HVIO Avio; 


Parameters 


/« pointer to structure for state information «/ 
/« video handle «/ . 


The VioGetState function retrieves the current settings of the screen-palette 
registers, the overscan (border) color, the blink/background intensity switch, the 
screen color, the underline position, or the target display. 


The VioSetState function is a family API function. 


pvoidState Points to the structure that receives the state information. The 
structure type, which depends on the request type specified in the type field of 
each structure, is one of the following: VIOPALSTATE, VIOOVERSCAN, 
VIOINTENSITY, VIOCOLORREG, VIOSETULINELOC, or VIOSETTARGET. 
These structures have the following forms: 


typedef struct _VIOPALSTATE { 
USHORT cb; 
USHORT type; 
USHORT iFirst; 
USHORT acolor [1]; 
} VIOPALSTATE; 


typedef struct _VIOOVERSCAN { 
USHORT cb; 
USHORT type; 
USHORT color; 

} VIOOVERSCAN; 


typedef struct _VIOINTENSITY { 
USHORT cb; 
USHORT type; 
USHORT fs; 

} VIOINTENSITY; 


typedef struct _VIOCOLORREG { 
USHORT cb; 
USHORT type; 
USHORT firstcolorreg; 
USHORT numcolorregs; 
PCH colorregaddr; 

} VIOCOLOR; 


Return Value 


Example 


See Also 


Changes 


Corrections 


VioReadCellStr 
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typedef struct _VIOSETULINELOC { 
USHORT cb; . 
USHORT type; 
USHORT scanline; 

} VIOUNDERLINE; 


typedef struct _VIOSETTARGET { 
USHORT cb; 
USHORT type; 
USHORT defaultalgorithm; 
} VIOTARGET; 


For each structure, you must set the cb and type fields before calling the func- 
tion. Not all values for the type field are valid for all screen modes. 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created by using the 
VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_LINVALID_LENGTH 


This example calls the VioGetState function to retrieve the settings for each of 
the 16 palette registers: 
BYTE abState[38]; 


PVIOPALSTATE pviopal; 
pviopal = (PVIOPALSTATE) abState; 


pviopal->cb = sizeof (abState); /* structure size */ 
pviopal->type = 0; /* retrieves palette registers i: 
pviopal->iFirst = 0; /* first palette register to return */ 


VioGetState(pviopal, 0); 
VioCreatePS, VioGetMode, VioSetState 


The VIOCOLORREG, VIOSETULINELOC, and VIOSETTARGET structures 
have been added to the list of possible structures for this function. 


The VioGetState function is a family API function. 


PCH pchCellString; 
PUSHORT pcb; 
USHORT usRow; 
USHORT usCo/umn; 


Correction 
USHORT VioReadCellStr( pchCellString, pcb, usRow, usCo/umn, hvio) 
/« pointer to buffer for string »/ 
/« pointer to variable for string length «/ 
/x starting location (row) »/ 
/» starting location (column) »/ 
/« video handle «/ 


HVIO hvio; 


The VioReadCellStr function reads one or more cells (character-attribute combi- 
nations) from the screen, starting at the specified location. If the string is longer 
than the current line, the function continues reading at the beginning of the next 
line but does not read past the end of the screen. 


The VioReadCellStr function is a family API function. 
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Parameters 


Return Value 


Example 


See Also 


Corrections 


VioScrollDn 


pchCellString Points to the buffer that receives the cell string. 


pcb Points to the variable that specifies the length (in bytes) of the buffer 
pointed to by pchCellString. The length should be an even number. On return, 
this function copies the length of the string to the variable. 


usRow — Specifies the row at which to begin reading the cell string. 
usColumn Specifies the column at which to begin reading the cell string. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


This example calls VioReadCellStr to read Line 0, then calls the VioWrtCellStr 
function to write the cell string to Line 24: 


CHAR achCells[160]; 
USHORT cb = sizeof (achCells) ; 


VioReadCellStr (achCells, /* buffer for string x / 
&eb, /* points to variable for string length */ 

O, /* starting location (row) / 

O, /* starting location (column) */ 

* video handle a/ 


0); 
asi (calaseniecncelie. cb, 24, O, O); 
VioReadCharStr, VioWrtCellStr 


The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 


Correction 


USHORT VioScrollDn( usTopRow, usLeftCol, usBotRow, usRightCol, cbLines, pbCell, hvio) 


USHORT usTopRow; 
USHORT usLeftCol; 
USHORT usBotRow; 


USHORT usRightCol; 


USHORT cbLines; 
PBYTE pbCell; 
HVIO hvio: 


Parameters 


/« top row »/ 
/« left column  s/ 
/«{ bottom row s/ 
/« right column »/ 


/«x number of blank lines »/ 

/« pointer to cell to write «/ 

/« video handle s/ 
The VioScrollDn function scrolls the current screen downward. 
The VioScrollDn function is a family API function. 


usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


Return Value 


Comments 


Example 


See Also 


Corrections 
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cbLines Specifies the number of lines to be inserted at the top of the screen 
area being scrolled. If this parameter is zero, no lines are scrolled. 


pbCell Points to a character/attribute combination, called a cell, that fills the 
screen area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper-left 
corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollDn function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum 
values. The function clears the screen by using the character/attribute combina- 
tion pointed to by the pbCell parameter. 


This example creates a cell containing the space character (0x20) and a white 
character attribute (0x07 on an EGA color monitor), and calls VioScrollDn to 
clear the screen by using this cell. By changing the character attribute, you could 
change the background color of the screen while clearing it at the same time 
(using ‘a value OxFFFF for usBotRow, usRightCol, and cbLines clears the 
screen): 


BYTE bCell [2]; 


bCell[O] = 0x20; /* space character */ 
bCell[1] = 0x07; /* white attribute (EGA) */ 
VioScrol1Dn (0, /* top row : 
i /* left column */ 
OxFFFF, /* bottom row */ 
OxFEFF, /* right column */ 
OxFFFEF, /* number of lines */ 
bCell, /* cell to write */ 
O); /* video handle */ 


VioCreatePS, VioScrollLf, VioScrollRt, VioScrollUp 


The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 
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M@ VioScrollLf 


USHORT usTopRow; 
USHORT usLeftCol; 
USHORT usSotRow; 


Correction 
USHORT VioScrollLf( usTopRow, usLeftCol, usBotRow, usRightCol, cbColumns, pbCell, hvio) 
/» top row »/ 
/» left column s/ 
/» bottom row »/ 
/« right column »/ 


USHORT usRightCol; 


USHORT cbColumns; /« number of biank columns »«/ 


PBYTE pbCell; 
HVIO hvio; 


Parameters 


Return Value 


Comments 


Example 


/« pointer to the cell to write «/ 
/x video handle »/ 


The VioScrollLf function scrolls the current screen toward the left. 
The VioScrollLf function is a family API function. 


usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbColumns _ Specifies the number of columns of spaces to be inserted at the 
right. If this parameter is zero, no columns are inserted. 


pbCell Points to a character/attribute combination, called a cell, that fills the 
screen area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper-left 
corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollLf function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their max- 
imum values. The function clears the screen by using the character/attribute 
combination pointed to by the pbCell parameter. 


This example calls VioScrollLf to fill the last ten columns at the right of the 
screen with red hearts on a black background (a value of OxPFFF i is used for 
usBotRow and usRightCol): 


VioScrollRt 281 


BYTE bCell[2]; 


bCell1[0] = 0x03; /* heart character a/ 

bCell[1] = 0x04; /7* red attribute (EGA) */ 

VioScrollLf (0, /* top row * 
O, 7* left column a/ 
OxFEFE, /* bottom row */ 
OxFFFEF, 7/* right column */ 
10, /* columns */ 
bCell, /* cell to write a/ 
O); /* video handle */ 


See Also VioCreatePS, VioScrollDn, VioScrolIRt, VioScrollUp 

Corrections The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 

VioScrollRt Correction | 

USHORT VioScrollRt( usTopRow, usLeftCo/, usBotRow, usRightCol, cbColumns, pbCell, hvio) 


USHORT usTopRow; 
USHORT usLeftCol; 
USHORT usBotRow; 


USHORT usRightCo/; 


USHORT cbColumns 
PBYTE pbCell; 
HVIO hvio; 


Parameters 


Return Value 


Comments 


/« top row »/ 
/« left column »/ 
/»« bottom row »/ 
/« right column a/ 
; /« number of blank columns / 
/« pointer to cell to write »/ 
/x video handle »/ 


The VioScrollRt function scrolls the current screen toward the right. 
The VioScroliRt function is a family API function. 


usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbColumns _ Specifies the number of columns of spaces to be inserted at the 
left. If this parameter is zero, no columns are inserted. 


pbCell Points to a character/attribute combination, called a cell, that fills the 
screen area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper-left 
corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the maximum value 
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Example 


See Also 
Corrections 


VioScrollUp 


for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollUp function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their max- 
imum values. The function clears the screen by using the character/attribute 
combination pointed to by the pbCell parameter. 


This example calls VioScrollRt to fill the first ten columns at the left of the 
screen with red hearts on a black background (a value of OxFFFF is used for 
usBotRow and usRightCol): 


BYTE bCell[2]; 


bCell[O] = 0x03; /* heart character a/ 
bCell[1] = 0x04; /* red attribute (EGA) */ 
VioScrollRt (0, /* top row a/ 
Oo, 7* left column */ 
OxFFFF, 7* bottom row a/ 
OxEFEFE, 7/* right column a/ 
10, /* columns */ 
bCell, /* cell to write */ 
O); /* video handle */ 


VioCreatePS, VioScrollDn, VioScrollLf, VioScrollUp 


The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 


Correction 


USHORT VioScrollUp( usTopRow, usLeftCol, usBotRow, usRightCol, cbLines, pbCell, hvio) 


USHORT usTopRow; /« top row »/ 
USHORT usLeftCol; /« left column »/ 
USHORT usBotRow; /« bottom row a/ 
USHORT usRightCol; /« right column s/ 


USHORT cbLines; 
PBYTE pbCell; 
HVIO hvio; 


Parameters 


/« number of blank lines »/ 

/» pointer to cell to write »/ 

/» video handle »/ 
The VioScrollUp function scrolls the current screen upward. 
The VioScrollUp function is a family API function. 


usTopRow _ Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbLines Specifies the number of blank lines to insert at the bottom of the 
screen area being scrolled. If this parameter is zero, no lines are inserted. 


pbCell Points to a character/attribute combination, called a cell, that fills the 
screen area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value 


Comments 


Example 


See Also 


Corrections 


VioSetCurType 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper-left 
corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollUp function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum 
values. The function clears the screen by using the character/attribute combina- 
tion pointed to by the pbCell parameter. 


This example calls VioScrollUp to scroll the entire screen up (by using the value 
OxFFFF for usBotRow, usRightCol, and cbLines) and to fill the screen area left 
blank by the scrolling with spaces on a green background (0x22 on an EGA 
color monitor): 


BYTE bCell[2]; 


bCell[0O] = 0x20; /* space character */ 
bCell[{1] = 0x22; /* green attribute (EGA) */ 
VioScrollUp (0, /* top row * 
P /* left column a/ 
OxFEFE, /* bottom row s/ 
OxFEFE, /* right column a/ 
OxFEFF, 7* number of lines s/ 
bCell, /* cell to write a/ 
/* video handle */ 


0); , 
VioSetCurPos(0, 0, 0); 
VioCreatePS, VioScrollDn, VioScrollLf, VioScrollRt 


The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 


Change 


USHORT VioSetCurType( pvioci, hvio) 
PVIOCURSORINFO pvioci; /» pointer to structure for cursor characteristics »/ 


HVIO hvio; 


Parameters 


/» video handle a/ 


The VioSetCurType function sets the cursor type. The cursor is a shared 
resource for all processes in a screen group. If one process changes it, it is 
changed for all processes in the group. 


The VioSetCurType function is a family API function. 


pvioci Points to the VIOCURSORINFO structure that specifies the charac- 
teristics of the cursor. The VIOCURSORINFO structure has the following form: 


typedef struct _VIOCURSORINFO { 
USHORT yStart; 
USHORT cEnd; 
USHORT cx; 
USHORT attr; 
} VIOCURSORINEO; 
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Return Value 


Comments 


Example 


See Also 


Changes 


VioSetMode 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously by 
using the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_WIDTH 


The yStart and cEnd fields of the VIOCURSORINFO structure can be set to 
values that are independent of the number of scan lines in the character cell. If 
you specify percentages for these values, MS OS/2 calculates the beginning and 
ending scan lines by multiplying the specified percentage by the number of scan 
lines in the character cell and rounding the total to the nearest scan line. Percen- 
tages are specified as a number in the range 0 through - 100. For example, if 
yStart is set to - 90 and cEnd is set to - 100, the cursor occupies the bottom 10 
percent of the character cell. 


This example calls the VioSetCurType function to set the current cursor type to 
a block cursor with 14 scan lines: 


VIOCURSORINEO vioci; 


vioci.yStart = 0; /* beginning scan line for cursor */ 
vioci.cEnd = 13; /* ending scan line, zero-based a/ 
vioci.cx = 0; /7* default width, one character a/ 
vioci.attr = 0; * normal attribute * 


VioSetCurType (&vioci, 0); 
VioCreatePS, VioGetCurType, VioSetCurPos 


The yStart and cEnd fields of the VIOCURSORINFO structure can be set to 
values that are independent of the number of scan lines in the character cell. If 
you specify percentages for these values, MS OS/2 calculates the beginning and 
ending scan lines by multiplying the specified percentage by the number of scan 
lines in the character cell and rounding the total to the nearest scan line. Percen- 
tages are specified as a number in the range 0 through - 100. For example, if 
yStart is set to - 90 and cEnd is set to - 100, the cursor occupies the bottom 10 
percent of the character cell. 


Change 


USHORT VioSetMode( pviomi, hvio) 
PVIOMODEINFO pviomi; /« pointer to structure for screen mode +/ 


HVIO fhvio; 


/x video handle »/ 


The VioSetMode function sets the screen mode. The screen mode defines the 
display mode (text or graphics), the number of colors being used (2, 4, or 16), 
and the width and height of the screen in both character cells and pels. VioSet- 
Mode also initializes the cursor position and type, but does not clear the screen. 


The VioSetMode function is a family API function. 


Parameters 


Return Value 


Comments 


Example 


See Also 


Changes 


Corrections 
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pviomi Points to the VIOMODEINFO structure that specifies the screen 
mode. The VIOMODEINFO structure has the following form: 


typedef struct _VIOMODEINFO { 
USHORT cb; 
UCHAR fbType; 
UCHAR ‘color; 
USHORT col; 
USHORT row; 
USHORT hres; 
USHORT vres; 
UCHAR attribfmt; 
UCHAR attribcount; 
ULONG pdbaddr; 
ULONG pdblen; 
ULONG fullbufsz; 
ULONG partbufsz; 
ULONG edaaddr; 

} VIOMODEINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hvio This parameter must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_INVALID_LENGTH 
ERROR_VIO_MODE 


Not all screen-mode values are valid for all displays. 


The hvio parameter can be only NULL. This function cannot be used by an 
advanced video-input-and-output application. 


When VioSetMode is called from a VIO-window application (as opposed to an 
application that is running in its own screen group), it does not change the size 
of a character cell. 


This example calls the VioGetMode function to retrieve the current display 
mode, changes the mode, and calls VioSetMode to enable the new display 
mode. 


VIOMODEINEFO viomi; 

viomi.cb = sizeof (viomi) ; 

VioGetMode (&viomi, 0); 

if (viomi.vres > 350) 
viomi.row = (viomi.row == 50) ? 25 : SO; 

else /* EGA display */ 
viomi.row = (viomi.row == 43) ? 25 : 43; 

VioSetMode(&viomi, 0); 


/* VGA display */ 


VioCreatePS, VioGetMode, VioSetState 


The VIOMODEINFO structure pointed to by the pviomi parameter contains 
several additional fields when used in MS OS/2, version 1.2. 


The hvio parameter can be only NULL. This function cannot be used by an 
advanced video-input-and-output application. 
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H VioSetState | Change 


USHORT VioSetState ( pvoidState, hvio) 
PVOID pvoidState; /« pointer to buffer with new state »«/ 
HVIO hvio; /« video handle »/ 


The VioSetState function sets the palette-register values, the overscan (border) 
color, the blink/background intensity, the screen color, the underline position, 
or the display adapter. 


The VioSetState function is a family API function. 


Parameters pvoidState Points to the structure that contains the request type and the 

values to set. The structure type, which depends on the request type specified in 
the type field of each structure, is one of the following: VIOPALSTATE, 
VIOOVERSCAN, VIOINTENSITY, VIOCOLORREG, VIOSETULINELOC, or 
VIOSETTARGET. These structures have the following forms: 


typedef struct _VIOPALSTATE { 
USHORT cb; 
USHORT type; 
USHORT iFirst; 
USHORT acolor [1]; 
} VIOPALSTATE; 


typedef struct _VIOOVERSCAN { 
USHORT cb; 
USHORT type; 
USHORT color; 

} VIOOVERSCAN; 


typedef struct _VIOINTENSITY { 
USHORT cb; 
USHORT type; 
USHORT fs; 

} VIOINTENSITY; 


typedef struct _VIOCOLORREG { 
USHORT ch; 
USHORT type; 
USHORT firstcolorreg; 
USHORT numcolorregs; 
PCH colorregaddr; 

} VIOCOLOR; 


typedef struct _VIOSETULINELOC { 
USHORT cb; 
USHORT type; 
USHORT scanline; 

} VIOUNDERLINE; 


typedef struct _VIOSETTARGET { 
USHORT cb; 
USHORT type; 
USHORT defaultalgorithm; 
} VIOTARGET; 


Not all request-type values are valid for all screen modes. 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created by using the 
VioCreatePS function. For other programs, hvio must be NULL. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_INVALID_LENGTH 


Example This example retrieves the current settings of the palette registers, switches 
palette registers #0 and #7, and calls VioSetState to enable the new settings: 


BYTE abState[38]; 

PVIOPALSTATE pviopal; 

USHORT usTmp; 

pviopal = (PVIOPALSTATE) abState; 
pviopal->cb = sizeof (abState) ; 


pviopal->type = 0; /* retrieves palette registers */ 
pviopal->iFirst = 0; /* first register to retrieve */ 
VioGetState(pviopal, 0); /* retrieves current settings */ 
usTmp = pviopal->acolor [0]; /* swaps #0 and #7 * 


pviopal->acolor[O] = pviopal->acolor [7]; 
pviopal->acolor[7] = usTmp; 


VioSetState(pviopal, 0); /* enables new settings */ 
See Also VioCreatePS, VioGetState, VioSetMode 
Changes The VIOCOLORREG, VIOSETULINELOC, and VIOSETTARGET structures 
have been added to the list of possible structures for this function. 
Corrections The VioSetState function is a family API function. 
VioShowBuf Correction 
USHORT VioShowBuf( offLVB, cbOutput, hvio) 
USHORT offLVB; /» offset into logical video buffer +/ 
USHORT cbOutput; /« length »/ 
HVIO Avio; /« video handle »/ 


The VioShowBuf function updates the physical screen from the logical video 
buffer (LVB). You may use the logical video buffer to directly manipulate infor- 
mation displayed on the screen. 


The VioShowBuf function is a family API function. 


Parameters offLVB Specifies the offset into the logical video buffer at which the screen 
update is to start. 


cbOutput Specifies the length (in bytes) of the screen area to update. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created using the 
VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_DETACHED 


Comments If a background process calls VioShowBuf, the function will return 
ERROR_VIO_DETACHED. 
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Example This example retrieves the address of the logical video buffer, makes changes to 
that buffer, and calls VioShowBuf to update the physical video buffer from the 
logical video buffer: 

PBYTE pbLVB; 

USHORT cbOutput; 

VioGetBuf((PULONG) &pbLVB, &cbOutput, 0); 

VioShowBuf (Oo, /* offset into logical video buffer 7 
cbOutput, /7* length of screen area 
0); /* video handle 24 

See Also VioCreatePS, VioGetBuf, VioGetPhysBuf 

Corrections This function is not a family API function. 

VioWrtCellStr Correction 

USHORT VioWrtCellStr( pchCelliString, cbCel/String, usRow, usColumn, hvio) 

PCH pchCellString; _/» pointer to cell string »/ 

USHORT cbCellString; /« length of string af 

USHORT usRow; /« starting position (row) »/ 

USHORT usColumn; /« starting position (column) «/ 

HVIO hvio; /» video handle »/ 


Parameters 


Return Value 


The VioWrtCellStr function writes a cell string to the screen. A cell string is one 
or more character/attribute combinations. A character/attribute combination 
defines the character to be written and the character attribute by which it is 
displayed. 


If the string is longer than the current line, the function continues writing it at 
the beginning of the next line, but does not write past the end of the screen. 


The VioWrtCellStr function is a family API function. 


pchCellString Points to the cell string to write. 


cbCellString Specifies the length (in bytes) of the cell string. The length 
should be an even number. 


usRow Specifies the row at which to start writing the cell string. 
usColumn Specifies the column at which to start writing the cell string. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


Example 


See Also 


Corrections 


VioWrtNCell 
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This example calls the VioWrtCellStr function to display the string “Hello 
World!” using 12 different attributes: 


CHAR achCellString[] = "H\le\21\31\40\5 \6W\70\10r\111\13d\14!"; 

VioWrtCellStr (achCellString, /* character/attribute string */ 
sizeof (achCellString), /* length of string * 
10, /* row */ 
35, /* column */ 
0); /* video handle a/ 


VioCreatePS, VioReadCellStr, VioWrtCharStr, VioWrtTTY 


The references to cells have been changed to reflect that an attribute can be 
longer than one byte. 


PBYTE pbCell; 
USHORT cb; 
USHORT usRow; 
USHORT usColumn; 


Correction 
USHORT VioWrtNCell( pbCell, cb, usRow, usCo/umn, hvio) . 
/x pointer to cell to write »/ 
/« number of times to write —«/ 
/» starting position (row) s/ 
/« starting position (column) «/ 
/» video handle «/ 


HVIO Avio; 


Parameters 


The VioWrtNCell function writes a cell to the screen a specified number of 
times. A cell (also called a character/attribute combination) consists of an 
unsigned byte value that specifies the character and one or more unsigned byte 
values that specify the attribute to be written. 


If the number of times that a cell is repeated is greater than the screen width, 
the VioWrtNCell function continues writing the cell at the beginning of the next 
line but does not write past the end of the screen. 


The VioWrtNCell function is a family API function. 


pbCell Points to the cell to write. 


cb Specifies the number of times to write the cell. 


Return Value 


usRow Specifies the row at which to start writing the cell." 
usColumn — Specifies the column at which to start writing the cell. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


290 VioWrtNCell 


Example This example calls the VioWrtNCell function to fill the screen with green capital 
letter A’s (on an EGA color monitor): 
BYTE abCell[2]; /* character/attribute pair */ 
abCell[0}] = 'A'; /* character (letter A) */ 
abCell[(1} = 0x02; /* attribute (green) a/ 
VioWrtNCell (abCell, /* address of attribute a/ 
80 * 25, /* number of cells to write */ 
O, /* row ; “7 
Oo, /* column */ 
0); /* video handle */ 
See Also VioCreatePS, VioWrtNChar 
Corrections The references to cells have been changed to reflect the fact that a attribute can 


be longer than one byte. 


WinAddProgram Change 
HPROGRAM WinAddProgram( hab, ppib, hGroupHandle) 

HAB hab; /« handle of anchor block »/ 

PPIBSTRUCT ppib; /« address of structure with program information «/ 

HPROGRAM AGroupHandle; /» handle of program group »/ 


The WinAddProgram function adds a program to the program list of a group. 
Program titles need not be unique, although duplicate titles within the same 
group are not allowed. 


Parameters hab Identifies the anchor block. 


ppib_ Points to a PIBSTRUCT structure that contains program information for 
the program being added to the program list. The PIBSTRUCT structure has the 
following form: 7 


typedef struct _PIBSTRUCT { 
PROGTYPE progt; 


CHAR szTitle [MAXNAMEL+1]; 

CHAR szIconFileName [MAXPATHL+1] ; 
CHAR szExecutable [MAXPATHL+1] ; 
CHAR szStartupDir [MAXPATHL+1]; 
XYWINSIZE xywinInitial; 

USHORT resl; 

LHANDLE res2; 

USHORT cchEnvironmentVars; 

PCH pcehEnvironmentVars; 
USHORT cchProgramParameter ; 

PCH pcohProgramParameter ; 


} PIBSTRUCT; 


hGroupHandle Identifies the program group to which the program is added. 


Return Value The return value is the handle for the program if the function is successful or 
NULL if an error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_DUPLICATE_TITLE 
PMERR_GROUP_PROTECTED 
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PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_PROGRAM_CATEGORY 
PMERR_INVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_LIN_IDX 


The WinAddProgram function provides compatibility with MS OS/2 1.1 and ear- 


Comments 
lier versions. Applications intended exclusively for MS OS/2 1.2 and later ver- 
sions should use the PrfAddProgram function. 

See Also PrfAddProgram, WinCreateGroup, WinQueryDefinition, WinQuery- 
ProgramTitles 

Changes This function has been replaced by the PrfAddProgram function. 

WinAssociateHelpInstance New 


BOOL WinAssociateHelpinstance ( hwndHelpinstance, hwndApp) 
HWND hwndHelpinstance; _—_/« handle of help instance o/ 


HWND hwndApp; 


Parameters 


Return Value 


Errors 


Comments 


See Also 


/« application-window handle «/ 


The WinAssociateHelpInstance function associates a help instance with a 
specified application window. 


hwndHelpInstance Identifies the help instance. It must have been previously 
created using the WinCreateHelpInstance function. 


hwndApp Identifies the application window with which the help instance is 
associated, or is NULL. If NULL, the association (if any) between the help 
instance and a window is removed. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


HMERR_INVALID_ASSOC_HELP_INST 
HMERR_INVALID_HELP_INSTANCE_HDL 
HMERR_NO_FRAME_WND_IN_CHAIN 
HMERR_INVALID_ASSOC_APP_WND 


A help instance can be associated with any application window that has a frame, 
but the help instance should contain help information relating to this application 
window and the windows in its window chain. 


WinCreateHelpInstance 
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—H WinBroadcastMsg Correction 


BOOL WinBroadcastMsg( hwnd, msg, mp7, mp2, fs) 


HWND hwnd; 
USHORT msg; 
MPARAM mp7; 
MPARAM mp2; 
USHORT fs; 


Parameters 


Return Value 


See Also 


Corrections 


/« handle of the parent window  »/ 


/» message »/ 
/« message parameter «/ 
/»x message parameter a/ 


/» windows to send message to «/ 


The WinBroadcastMsg function broadcasts a message to multiple windows. This 
function sends or posts a message to all immediate child windows of the 
specified window. 


hwnd Identifies the window whose immediate child windows will receive the 
message. If this parameter is HWND_DESKTOP, the function sends the mes- 
sage to all main windows on the screen. 


msg Specifies the message. 
mpl _ Specifies the first message parameter. 
mp2 Specifies the second message parameter. 


fs Specifies which windows to send the message to, and whether the message 
should be sent or posted. The value consists of a flag from each of the following 
lists combined using the OR operator. 


The following list contains the values specifying which windows to broadcast the 
message to: . 


Destination Meaning 


BMSG_DESCENDANTS Post or send the message to Awnd and all of its 
descendants. 
BMSG_FRAMEONLY Post or send the message to frame windows only. 


The following list contains the values specifying how to broadcast the message 
(send or post): 


Value Meaning 

BMSG_POST Post a message to all child windows of the window 
specified by the hwnd parameter. 

BMSG_POSTQUEUE _ Post a message to all threads that have a message 
queue. The message’s hwnd parameter will be 
NULL. 

BMSG_SEND Send a message to all children of the window 


specified by the hwnd parameter. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


WinPostMsg, WinSendMsg 


To broadcast a message to all windows in the system, the hwnd parameter must 
be set to HWND_DESKTOP, not to NULL. 
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M@ WinCreateFrameControls Correction 


BOOL WinCreateFrameControls( hwndFrame, pfcdata, pszTitle, hmod) 
HWND hwndFrame; /« handle of the frame window «/ 
PFRAMECDATA pfcdata; /« address of structure »/ 
PSZ pszTiile; /« address of title-bar string —+/ 


The WinCreateFrameControls function creates standard frame controls for a 
specified window. This function is used when the standard frame controls are 
needed for a nonstandard window; for example, with a window with a class 
other than WC_FRAME. 


Parameters hwndFrame Identifies the frame window that becomes the parent and owner 
window of all the frame controls created. 


Pfcdata Points to the FRAMECDATA structure that contains information 
about the frame controls that are to be created. The FRAMECDATA structure 
has the following form: 


typedef struct _FRAMECDATA { 
USHORT cb; 


ULONG flCreateFlags; 
HMODULE hmodResources; 
USHORT idResources; 


} FRAMECDATA; 


pszTitle Points to a null-terminated string displayed in a title-bar control. 


Return Value The return value is TRUE if the function is successful or FALSE if an error 


occurs. 
See Also WinCreate Window 
Corrections The syntax incorrectly listed an hmod parameter. This function only has three 


parameters, not four. 


M@ WinCreateGroup Change 
HPROGRAM WinCreateGroup( hab, pszTitle, fVisible, hprogDest, pszHelp) 
HAB hab; /x handle of anchor block »/ 
PSZ pszTitle; /« address of group title »/ 
BYTE fvVisible; /« visibility flag »/ 
HPROGRAM hprogDest; /« handle of destination group «/ 
PSZ pszHelp; /» address of help text «/ 


The WinCreateGroup function creates a new program-group entry in Desktop 
Manager. The new group is created empty. The WinAddProgram function must 
be used to add program entries to the group. If the group already exists, the han- 
dle of the existing group is returned. 


Parameters hab Identifies the anchor block. 
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Return Value 


Errors 


Comments 


See Also 
Changes 


pszTitle Points to the title of the new group. The maximum string size is 
defined by the MAXNAMEL constant. Strings that exceed this limit are trun- 
cated to MAXNAMEL characters. Leading and trailing blanks are removed. 
The string must contain at least one nonblank character and must not contain a 
backslash (\). 


fVisible Specifies the visibility of the new group. If this parameter is 
SHE_VISIBLE, the group is visible (it can be viewed by the end-user). If this 
value is SHE_INVISIBLE, the group is invisible. 


hprogDest Identifies the program group into which the new group is placed. If 
this parameter is NULL, the new group is placed in the root group. 


pszHelp Points to a null-terminated string that is used as a short piece of help 
information relating to the new program group. This parameter is optional and 
can be NULL. If used, the string must contain at least one nonblank character 
and be less than 60 characters in length. 


The return value is the group handle for the group if the function is successful. 
Otherwise, the return value is NULL, indicating that an error occurred. 


Use the WinGetErrorInfo function to retrieve the error value, which may be one 
of the following: 


PMERR_INSUFF_SPACE_TO_ADD 
PMERR_INVALID_GROUP_HANDLE 
~’ PMERR_LINVALID_TARGET_HANDLE 
PMERR_INVALID_TITLE 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


The WinCreateGroup function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfCreateGroup function. 

PrfCreateGroup, WinAddProgram 


This function has been replaced by the PrfCreateGroup function. 


WinCreateHelpInstance . New 
HWND WinCreateHelpinstance( hab, phminitStructure) 


HAB hab; 


/x anchor-block handle s/ 


PHELPINIT phminitStructure; /« pointer to help structure »/ 


Parameters 


The WinCreateHelpInstance function creates a help instance. A help instance is 
an “object” window that process help requests from the application and the user. 


hab Identifies the application anchor block. It must have been previous creat- 
ing using the WinInitialize function. 


phmInitStructure Points to the HELPINIT structure. The HELPINIT struc- 
ture has the following form: 
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typedef struct _HELPINIT { 


USHORT cBytes; 

ULONG ulReturnCode; 

PSZ pszTutorialName; 

PHELPTABLE phtHelpTable; 

HMODULE hmodHelpTableModule; 

HMODULE hmodAccelActionBarModule; 

USHORT idAccelTable; 

USHORT idActionBar; 

PSZ pszHelpWindowTitle; 

USHORT usShowPanelld; 

PSZ pszHelpLibraryName; 
} HELPINIT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is the handle of the help instance created if the function is suc- 
cessful or NULL if an error occurs. 


See Also WinCreateHelpTable, WinDestroyHelpInstance, WinInitialize, WinLoad- 
HelpTable 
@ WinCreateHelpTable New 
BOOL WinCreateHelpTable ( hwndHelpinstance, phtHelpTable) 
HWND hwndHelpinstance; /« handle of help instance »/ 


PHELPTABLE phtHelpTable; /» pointer to structure with help table »/ 


The WinCreateHelpTable function replaces the existing help table (if any) with 
the help table pointed to by phtHelpTable. 


Parameters hwndHelpInstance Identifies the help instance. It must have been previously 
created using the WinCreateHelpInstance function. 


phtHelpTable Points to a HELPTABLE structure containing window and 
corresponding help panel IDs. The HELPTABLE structure has the following 


form: 

typedef struct _HELPTABLE { 
USHORT idAppWindow; 
PHELPSUBTABLE phstHelpSubTable; 
USHORT idExtPanel; 


} HELPTABLE; 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Comments Applications can use this function to replace a help instance’s initial help table 
or to set the table if no initial help table is given. The initial help table is 
specified in the HELPINIT structure when the help instance is created with the 
WinCreateHelpInstance function. The function replaces the help table without 
freeing any memory or resources associated with the initial help table. 


See Also WinCreateHelpInstance, HM_CREATE_HELP_TABLE 
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H WinCreatePointerIndirect New 
HPOINTER WinCreatePointerlIndirect ( hwndDesktop, pptri) 
HWND hwndDesktop; /»« desktop handle »/ 


PPOINTERINFO pptri; /« pointer to structure with bitmap «/ 


The WinCreatePointerIndirect function creates a pointer by using the 
POINTERINFO structure. It can create a color pointer. 


Parameters hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


pptri Points to the POINTERINFO structure that contains the bitmap used to 
create the pointer image. The POINTERINFO structure has the following form: 
typedef struct  _POINTERINEO { 

BOOL fPointer; 

SHORT xHotspot; 

SHORT yHotspot; 


HBITMAP hbmPointer; 
} POINTERINEO; 


Return Value The return value is the handle of the new pointer if successful or NULL if an 
error occurs. 


Comments The WinCreatePointerIndirect and WinCreatePointer functions are similar. The 
difference between them is that the WinCreatePointerIndirect function can 
create a color pointer; the WinCreatePointer function can create only a black- 
and-white pointer. 


See Also WinCreatePointer 


H WinCreateSwitchEntry New 


HSWITCH WinCreateSwitchEntry( hab, pswet!) 
HAB hab; /« anchor-block handle »/ 
PSWCNTRL pswet; /» pointer to structure with new entry information »/ 


The WinCreateSwitchEntry function creates an entry in the switch list (the list 
of running programs displayed in the Task List). 


Parameters hab Identifies the anchor block. 


pswetl Points to the SWCNTRL structure that contcins information about the 
new switch-list entry. If the szSwtitle field in the SWCNTRL structure is NULL, 
the system uses the name under which the application was started. 


This applies only to the first call to this function for that program (since the pro- 
gram was started). Otherwise, a NULL entry name is invalid. The SWCNTRL 
structure has the following form: 
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typedef struct _SWCNTRL { 
HWND hwnd; 
HWND hwndIcon; 
HPROGRAM hprog; 
USHORT idProcess; 
USHORT idSession; 


UCHAR uchVisibility; 
UCHAR fbJump; 
CHAR szSwtitle [MAXNAMEL+1]; 
BYTE fReserved; 
} SWCNTRL; 


Return Value The return value is a handle to the new switch-list entry, or NULL if an error 
occurs. 


Comments The WinCreateSwitchEntry and WinAddSwitchEntry functions are similar. The 
only difference between them is that WinCreateSwitchEntry takes an anchor- 
block handle as the first parameter. 


Leading and trailing blanks are removed from the title. The title is truncated to 
60 characters. 


Example This example calls WinQueryWindowProcess to get the current process 
identifier (needed for the SWCNTRL structure). It then sets up the SWCTL 
structure and calls WinCreateSwitchEntry to add the program’s name to the 
Task List. 


The returned handle can be used in subsequent calls to WinChangeSwitchEntry 
if the title needs to be changed. 


The variables swctl, hswitch, and pid should be global if your application will be 
calling the WinChangeSwitchEntry function to avoid having to set up the struc- 
ture again. 


SWCNTRL swetl; 
HSWITCH hswitch; 


PID pid; 
HAB hab; 
hab = WinQueryAnchorBlock (hwndFrame) ; . /* gets anchor block */ 
WinQueryWindowProcess(hwndFrame, &pid, NULL); /* gets process id a/ 


swetl.hwnd = hwndFrame; /* window handle * 
swetl.hwndIcon = NULL; /* icon handle * 
swotl.hprog = NULL; /* program handle * 
swctl.idProcess = pid; /* process identifier * 
swotl.idSession = NULL; 7* session identifier * 
swetl.uchVisibility = SWL_VISIBLE; /7* visibility 

swotl.fbJump = SWL_JUMPABLE; /* jump indicator * 
swoetl.szSwtitle[O] = NULL; /* program name * 


hswitch = WinCreateSwitchEntry (hab, &swetl) ; 


See Also WinAddSwitchEntry, WinChangeSwitchEntry, WinRemoveSwitchEntry 
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— WinCreateWindow Change 
HWND WinCreateWindow( hwndParent, pszClass, pszName, flStyle, x, y, cx, cy, hwndQOwner, 


hwndinsertBehind, id, pCtIData, pPresParams) 


HWND hwndParent; /« parent-window handle »/ 
PSZ pszClass; /» pointer to registered class name »/ 
PSZ pszName; /» pointer to window text »/ 
ULONG fiStyle; /»« window style »/ 
SHORT x; /» horizontal position of window »/ 
SHORT jy; /« vertical position of window »/ 
SHORT cx; /» window width »/ 
SHORT cy; /» window height »/ 
HWND hwndOwner; /« owner-window handle »/ 
HWND hwndinsertBehind; /« handle to sibling window »/ 
USHORT jd; /« window identifier »/ 
PVOID pCtiData; /« pointer to buffer »/ 
PVOID pPresParams; /« pointer to structure with pres. params. »/ 


Parameters 


The WinCreateWindow function creates a new window. 


hwndParent Specifies the parent window of the new window. Any valid win- 
dow handle can be used. 


pszClass_ Points to the registered class name. This parameter can be an 
application-specified name (defined by the WinRegisterClass function), the 
name of a preregistered window class, or a window-class (WC) constant. 


pszName Points to window text or other class-specific data. The actual struc- 
ture of the data is class-specific. This data is usually a null-terminated string and 
is often displayed in the window. 


fiStyle Specifies the window style. It can be a combination of one or more of 
the following values: 


Value — Meaning 

WS_CLIPCHILDREN Prevents a window from painting over its child 
windows. . 

WS_CLIPSIBLINGS Prevents a window from painting over its sibling 
windows. 

WS_DISABLED Disables mouse and keyboard input to the win- 


dow. It is used to temporarily prevent the user 
from using the window. 


WS_MAXIMIZED Enlarges the window to the maximum size. 

WS_MINIMIZED Reduces the window to the minimum size. 

WS_PARENTCLIP Prevents a window from painting over its parent 
window. 

WS_SAVEBITS Saves the image under the window as a bitmap. 


When the window is moved or hidden, the sys- 
tem restores the image by copying the bits. 
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Value Meaning 


WS_SYNCPAINT Causes the window to immediately receive 
WM_PAINT messages after a part of the win- 
dow becomes invalid. Unless this style is set, the 
window receives WM_PAINT messages only 
when no other message is waiting to be pro- 
cessed. 


WS_VISIBLE Makes the window visible. This window is drawn 
on the screen unless overlapping windows com- 
pletely obscure it. Windows without this style 
are hidden. 


x Specifies the horizontal position of the window, relative to the origin of the 
parent window. 


y Specifies the vertical position of the window, relative to the origin of the 
parent window. . 


cx Specifies the window width, in pels. 
cy Specifies the window height, in pels. 
hwndOwner Identifies the owner window. 


hwndInsertBehind Identifies the sibling window behind which the specified 
window is placed. If this parameter is HWND_TOP, the specified window is 
placed on top of all its sibling windows. If this parameter is HWND_BOTTOM, 
the specified window is placed behind all its sibling windows. If the hwnd Insert- 
Behind parameter is neither HWND_TOP nor HWND_BOTTOM, or it is not a 
child window of the window identified by hwndParent, NULL is returned. 


id Specifies the window identifier (a value given by the application that allows 
a specific child window to be identified). For example, the controls of a dialog 
box have unique identifiers so that an owner window can distinguish which con- 
trol has notified it. Window identifiers are also used for frame windows. 


pCtlData Points to the buffer that contains class-specific information. This 
data is passed to the window procedure by the WM_CREATE message. 


pPresParams Points to a PRESPARAMS structure that contains presentation 
parameters for the window. This parameter is NULL if there are no presentation 
parameters. The PRESPARAMS structure has the following form: 
typedef struct _PRESPARAMS { 

ULONG cb; 


PARAM aparam[1]; 
} PRESPARAMS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is the handle of the window if the function is successful or 
NULL if an error occurs. 


Comments The WinCreateWindow function sends a WM_CREATE message to the 
window procedure of the window being created, and then sends the 
WM_ADJUSTWINDOWPOS message before the window is displayed. The 
values passed are those given to the WinCreate Window function. 
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The WM_SIZE message is not sent by WinCreateWindow while the window is 
being created. Any required size processing is performed during the processing 
of the WM_CREATE message. 


See Also WinCreateStdWindow, WinQueryObjectWindow, WinRegisterClass 
Changes _ The pPresParams parameter now points to a PRESPARAMS structure. 


WinDeleteLibrary | New 


BOOL WinDeleteLibrary( hab, hlib) 
HAB hab; /» anchor-block handle »/ 
HLIB Alib; /» handle of library to be deleted «/ 


The WinDeleteLibrary function deletes a library previously loaded by the Win- 
LoadLibrary function. 
Parameters hab Identifies the anchor block. 


hlib Identifies the library to be deleted. This handle must have been created 
by the WinLoadLibrary function. 


Return Value The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


See Also WinLoadLibrary 


WinDeleteProcedure New 


BOOL WinDeleteProcedure (hab, pfnwpProc) 
HAB hab; /»« anchor-block handle sf 
PFNWP pfnwpProc; /« pointer to window function »«/ 


The WinDeleteProcedure function deletes a procedure that was previously 
loaded using the WinLoadProcedure function. 


Parameters hab — Identifies the anchor block. 


PfnwpProc Points to the procedure to be deleted. This procedure must have 
been previously loaded by the WinLoadProcedure function. 


Return Value The return value is TRUE if the function is successful or FALSE if an error 


occurs. 
See Also WinDeleteLibrary, WinLoadProcedure 
WinDestroyHelpInstance New 


BOOL WinDestroyHelpIinstance ( hwndHelpinstance) 
HWND hwndHelpinstance; /» handle of instance to destroy «/ 


_. The WinDestroyHelpInstance function destroys a help instance. 


Parameters 


Return Value 


See Also 


WinDrawBitmap 


WinDrawBitmap = 301 


hwndHelpInstance Identifies the help instance to destroy. This handle must 
have been previously created by using the WinCreateHelpInstance function. 


The return value is TRUE if the help instance is successfully destroyed or 
FALSE if an error occurs. 


WinCreateHelpInstance 


Correction 


BOOL WinDrawBitmap( hpsDst, hbm, prc/Src, pptiDst, cirFore, cirBack, fs) 


HPS hpsDst; 
HBITMAP hbm; 
PRECTL prciSrc; 
PPOINTL pptiDst; 
LONG cirFore; 
LONG cirBack; 
USHORT fs; 


Parameters 


/« handle of the destination presentation space —«/ 


/« handle of the bitmap »/ 
/« address of structure with rectangle coordinates »/ 
/» address of structure with bitmap position «/ 
/« color of the foreground »/ 
/« color of the background «/ 
/« bitmap-drawing flags »/ 


The WinDrawBitmap function draws a bitmap using the current image colors 
and mixes. 


hpsDst Identifies the presentation space in which the bitmap is drawn. 
hbm Identifies the bitmap. 


prelSrc Points to the RECTL data structure that contains the coordinates of 
the rectangle to be drawn. If this parameter is NULL, the entire bitmap is 
drawn. The RECTL structure has the following form: 
typedef struct _RECTL { 

LONG xLeft; 

LONG yBottom; 

LONG xRight; 

LONG yTop; 
} RECTL; 


pptlDst Points to the position of the lower left of the bitmap in the presenta- 
tion space (in device coordinates). 


clrFore Specifies the color of the foreground. 
clrBack Specifies the color of the background. 
fs Specifies the flags that determine how the bitmap is drawn. It can be one of 
the following values: 
Value Meaning 


DBM_HALFTONE Use the OR operator to combine the bitmap with an 
alternating pattern of ones and zeros before drawing 
it. This flag can be used in conjunction with either 


DBM_NORMAL or DBM_INVERT. 

DBM_IMAGEATTRS _ The clrFore and clrBack parameters are ignored and 
the image attribute colors already selected in hpsDst 
are used instead. 


DBM_INVERT Draw the bitmap inverted, using 
ROP_NOTSRCCOPY. 
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Return Value 


Value Meaning 
DBM_NORMAL Draw the bitmap normally, using ROP_SRCCOPY. 
DBM_STRETCH The pptlDst parameter points to a RECTL data struc- 


ture, representing a rectangle in the destination 
presentation space to which the bitmap should be 
stretched. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


See Also GpiCreateBitmap, GpiLoadBitmap, WinGetSysBitmap 
Corrections The previous documentation incorrectly states that the pptlDst parameter was 
specified in presentation-space coordinates. This parameter is specified in device 
coordinates. 
HZ WinEnumDigitem Change 


HWND WinEnumDigitem( hwndDig, hwnd, code, flock) 


HWND hwndaDig; 
HWND hwnd; 
USHORT code; 
BOOL fLock; 


Parameters 


/» handle of the dialog window +/ 
/« handle of the child window _ «/ 
/« dialog item to return s/ 
/» lock/unlock flag »/ 


The WinEnumDiglItem function returns the handle of a dialog item within a dia- 
log window. 


hwndDlg Identifies the dialog window that contains the dialog item. 


hwnd Identifies the child window of the dialog window. This may be an 


immediate child window or a window lower in the hierarchy, such as a child of a 
child window. : 


code _ Specifies which dialog item to return. This parameter is one of the fol- 
lowing values: 


Value | Meaning 


EDI_FIRSTGROUPITEM First item in same group. 

EDI_LFIRSTTABITEM First item in dialog window with style 
WS_TABSTOP. The hwnd window is ignored. 

EDI_LLASTGROUPITEM Last item in same group. 

EDI_LASTTABITEM Last item in dialog box with style 
WS_TABSTOP. The hwnd window is ignored. 

EDI_LNEXTGROUPITEM Next item in same group. Wraps to beginning of 
group when end of group is reached. 


EDI_NEXTTABITEM Next item with style WS_TABSTOP. Wraps 
around to beginning of dialog-item list when end 
is reached. 

EDI_PREVGROUPITEM Previous item in same group. Wraps to end of 
group when start of group is reached. 


Return Value 


See Also 
Changes 


WinGetDIgMsg 
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Value Meaning 

EDI_PREVTABITEM Previous item with style WS_TABSTOP. Wraps 
to end of dialog-item list when beginning is 
reached. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 

The return value is the item handle obtained by this function, specified by the 
code parameter. The window is always an immediate child window of the win- 
dow identified by the hwndDig parameter. 

WinBeginEnumWindows, WinLockWindow 


The fLock parameter is ignored in MS OS/2, version 1.2. 


New 


BOOL WinGetDIgMsg( hwnd, pqmsg) 


HWND hwnd; 


PQMSG paqmsg; 


Parameters 


Return Value 


Comments 


/« dialog-window handle »/ 
/« pointer to structure with message +/ 


The WinGetDlgMsg function retrieves a message intended for a dialog box. This 
function is used by an application written in a language (for example, COBOL, 
or FORTRAN) that does not allow the system to call the application’s window 
procedure (this is called a non-reentrant window procedure). 


hwnd Identifies the dialog window. 


pqmsg_ Points to the QMSG structure that contains a message. The QMSG 
structure has the following form: 


typedef struct _QMSG { 
EWND hwnd; 
USHORT msg; 
MPARAM mp1; 
MPARAM mp2; 
ULONG time; 
POINTL ptl; 
} QMSG; 


The return value is TRUE if there is a message for the dialog box, or it is 
FALSE if the dialog is complete or an error occurs. 


The WinGetDlgMsg function allows a language that cannot support window pro- 
cedures to provide the function of a modal dialog window. The application 
creates a modeless box dialog by using the WinCreateDlg or WinLoadDlg func- 
tions and then calls WinGetDlgMsg to process messages associated with the dia- 
log box. The application should call this function in a loop until it receives a 
WML_QUIT message. The application should call WinDefDlgProc for the mes- 
sages it does not want rather than dispatching the messages it receives. 


To create a window that uses a non-reentrant window procedure, use NULL for 
the pfnWndProc parameter of the WinRegisterClass function. 
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The first time this function is called, the owner of the window specified by hwnd 
is disabled, thereby preventing input into windows other than the dialog box. 
The owner of the window specified by hwnd is enabled when the WinDismissDlg 
function is issued by the application or by the default dialog procedure. 


Synchronous messages that would normally go directly to the window procedure 
will be converted to one of the following messages and retrieved by the WinGet- 
DigMsg function: 


WM_PPAINT 
WM_PSETFOCUS 
WM_PSYSCOLORCHANGE 
WM_PSIZE 
WM_PACTIVATE 
WM_PCONTROL 


See Also WinCreateDlg, WinDefDlgProc, WinDismissDlg, WinLoadDlg, WinRegister- 
Class 


WinGetNextWindow Change 


HWND WinGetNextWindow( henum) 
HENUM henum; /» handle of the enumeration list »/ 


The WinGetNextWindow function obtains the handle of the next window ina 
specified enumeration list. 


The enumeration list details the window hierarchy at the time WinBegin- 
EnumWindows was called. Enumeration starts with the top-most child window 
(listed first) and proceeds through the list each time the function is called, until 
all windows have been enumerated. Once all windows have been enumerated, 
the function returns NULL. The enumeration then returns to the top of the list 
and the handle of the top-most child window is returned on the next call. 


Parameters henum Identifies the enumeration list. This parameter is created by the Win- 
BeginEnumWindows function. 

Return Value The return value is the handle of the next window in the enumeration list, or it is 
NULL if an error occurs. 

See Also WinBeginEnumWindows, WinLockWindow 

Changes This function no longer locks the window. 

WinGetSysBitmap Change 

HBITMAP WinGetSysBitmap( hwndDesktop, ibm) 

HWND hwndDesktop; /« handle of the desktop »/ 

USHORT ibm; /« index of the system bitmap «/ 


The WinGetSysBitmap function returns a handle to one of the standard bitmaps 
provided by the system. This bitmap can be used for any of the normal bitmap 
operations. When your application is done with the bitmap, it should free it by 
calling GpiDeleteBitmap. 


Parameters 
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hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


ibm Specifies the system-bitmap index value. It can be one of the following 
values: 


Value 


SBMP_BTNCORNERS 
SBMP_CHECKBOXES 
SBMP_CHILDSYSMENU 


SBMP_COMBODOWN 
SBMP_DRIVE 


SBMP_FILE 


SBMP_FOLDER 


SBMP_MAXBUTTON 
SBMP_MENUATTACHED 


SBMP_MENUCHECK 
SBMP_MINBUTTON 
SBMP_PROGRAM 


SBMP_RESTOREBUTTON 
SBMP_SBDNARROW 
SBMP_SBDNARROWDEP 
SBMP_SBDNARROWDIS 
SBMP_SBLFARROW 
SBMP_SBLFARROWDEP 
SBMP_SBLFARROWDIS 
SBMP_SBRGARROW 
SBMP_SBRGARROWDEP 
SBMP_SBRGARROWDIS 
SBMP_SBUPARROW 
SBMP_SBUPARROWDEP 
SBMP_SBUPARROWDIS 
SBMP_SIZEBOX 


SBMP_SYSMENU 


Meaning 


Push button corners. 
Check box/radio button check mark. 


Smaller version of the system menu bitmap to 
use in child windows. 


Combo-box down arrow. 


A symbol used by the file system to indicate a 
disk drive. 


A symbol used by the file system to indicate a 
file. 


A symbol used by the file system to show 
subdirectories. 


Maximize button. 


A symbol used to indicate that a menu item 
has an attached hierarchical menu. 


Menu check mark. 
Minimize button. 


A symbol used by the file system to indicate 


that a file is an executable program. 


Restore button. 

Scroll-bar down arrow. 

Scroll-bar down arrow is pressed. 
Scroll-bar down arrow is disabled. 
Scroll-bar left arrow. 

Scroll-bar left arrow is pressed. 
Scroll-bar right arrow is disabled. 
Scroll-bar right arrow. 

Scroll-bar right arrow is pressed. 
Scroll-bar right arrow is disabled. 
Scroll-bar up arrow. 

Scroll-bar up arrow is pressed. 
Scroll-bar up arrow is pressed. 


A symbol used to indicate an area of a win- 
dow that a user can click to resize the win- 
dow. 


System menu. 
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Return Value 


Value Meaning 


SBMP_TREEMINUS A symbol used by the file system to show that 
an entry in the directory tree contains no 
more files. 


SBMP_TREEPLUS A symbol used by the file system to show that 
' an entry in the directory tree contains more 
files. 


The return value is a handle to a bitmap, or it is NULL if an error occurs. 


See Also GpiDeleteBitmap, WinDrawBitmap 

Changes The following system bitmaps have been added: 
Value . Meaning 
SBMP_SBUPARROWDEP Scroll-bar up arrow is pressed. 
SBMP_SBDNARROWDEP Scroll-bar down arrow is pressed. 
SBMP_SBLFARROWDEP Scroll-bar left arrow is pressed. 
SBMP_SBRGARROWDEP Scroll-bar right arrow is pressed. 
SBMP_SBUPARROWDIS Scroll-bar up arrow is disabled. 
SBMP_SBDNARROWDIS Scroll-bar down arrow is disabled. 
SBMP_SBLFARROWDIS Scroll-bar right arrow is disabled. 
SBMP_SBRGARROWDIS Scroll-bar right arrow is disabled. 
SBMP_COMBODOWN Combo-box down arrow. 

— WinlnstStartApp New 
HAPP WinlnstStartApp ( hini, hwndNotifyWindow, cCount, pszApp, pszCmdLine, pData, fsOption) 
HINI hini; /« initialization-file handle »/ 

HWND hwndNotifyWindow; /« notification-window handle »/ 
USHORT cCount; /« count of elements in the application array »/ 
PSZ * pszApp; /» identifier of application. »/ 
PSZ pszCmdLine; /« input parameters for application »/ 
PVOID pData; /«{ must be zero »/ 
USHORT fsOptions; /» option flags »/ 


Parameters 


The WinInstStartApp function starts an installed application. 


-hini Specifies the handle of the initialization file where the application is 


found. 


hwndNotifyWindow Identifies the window to which a notification message 
should be sent. If this parameter is NULL, no notification message is sent. 


cCount Specifies the number of elements in the array pointed to by the 
pszApp parameter. This value must be 1 or 2. 


pszApp Points to an array of pointers which, in turn, point to strings that con- 
tain the name of the application and group (if any) where the application is 
found. The first element of the array points to the application name, the second 
to the group name. 
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pszCmdLine Points to the string that contains the command line to be passed 
to the application. 


pData Reserved value; must be zero. 


fsOptions Specifies the options to be used to start the application. This 
parameter can be one of the following values: 


Value Meaning 


SAF_LINSTALLEDCMDLINE ~— The command-line parameters in the Task 
List are used. Any parameters specified by 
pszCmdLine are ignored. 


SAF_STARTCHILDAPP The application is started as a child session 
of the session from which the WinInst- 
StartApp function is called. 


Return Value The return value is a handle to the application started if the function is success- 
ful or NULL if an error occurs. 


Errors: Possible errors may be retrieved with the WinGetLastError function, and may 
be one of the following: 


PMERR_INVALID_PARAMETERS 
PMERR_INVALID_APPL 
PMERR_LINVALID_WINDOW 
PMERR_CANNOT_START 
PMERR_STARTED_IN_BACKGROUND 


PMERR_DOS_ERROR 
PMERR_NOT_ENOUGH_MEM 
See Also WinTerminateApp 
WinlsWindowShowing | New 


BOOL WinlsWindowShowing( hwnd) 
HWND hwnd; /x window handle «/ 


The WinIsWindowShowing function determines if all or part of a window is 
currently displayed on the screen. This is in contrast to the WinIsWindowVisible 
function, which returns the actual visibility state of the window rather than its 
displayed state. 


Parameters hwnd Identifies the window to be checked. 


Return Value The return value is TRUE if any part of the identified window is visible, it is 
FALSE if no part of the window is visible. ; 


Comments The WinIsWindowShowing function also returns FALSE if it is called while the 
user is moving a window. 


See Also WinIsWindowEnabled, WinIsWindowVisible 
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WinLoadHelpTable | New 


BOOL WinLoadHelpTable ( hwndHelpinstance, idHelpTable, hmodModule) 
HWND = hwndHelpinstance; /« handle of help instance —+/ 
USHORT idHelpTable; /« resource ID for help table »/ 
HMODULE hmodModule; /« resource-module handle :/ 


The WinLoadHelpTable function specifies a help table for the given help 
instance. 


Parameters hwndHelpInstance Identifies the help instance. The instance must have been 
previously created using the WinCreateHelpInstance function. 
idHelpTable Specifies the resource ID of the help table. 
hmodModule Identifies the module that contains the help table resource. 


Return Value The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be the 
following: 


HMERR_HELP_INST_CALLED_INVALID 


Comments Applications can use this function to replace a help instance’s initial help table 
or to set the table if no initial help table is given. The initial help table is 
specified in the HELPINIT structure when the help instance is created with the 
WinCreateHelpInstance function. The function replaces the help table without 
freeing any memory or resources associated with the initial help table. 


See Also WinCreateHelpInstance, HM_LOAD_HELP_TABLE 

WinLoadLibrary New 
HLIB WinLoadLibrary( hab, pszModName) 

HAB hab; /x anchor-block handle _ »/ 


PSZ pszModName; /« pointer to library name «/ 


The WinLoadLibrary function loads a dynamic-link module and returns a handle 
for the module. You can use the module handle to retrieve the ae addresses 
of procedures in the module. 


Parameters hab Identifies the anchor block. 


pszModName_ Points to a null-terminated string; the string must be a valid 
MS OS/2 filename that specifies the path and filename of the dynamic-link 


module to be loaded. ie dynamic-link modules have the .dil filename extension 
by default. 


Return Value The return value is the handle of the library module, or it is NULL if an error 
occurs. 


See Also DosLoadModule, WinDeleteLibrary, WinLoadProcedure 
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a WinLoadProcedure New 


PFNWP WinLoadProcedure ( hab, hlib, pszProcName) 
HAB hab; /x anchor-block handle »/ 
HLIB Alib; /« handle of library »/ 
PSZ pszProcName; /»« pointer to procedure name «/ 


The WinLoadProcedure function loads a window procedure from the specified 
dynamic-link library. 


Parameters hab Identifies the anchor block. 


hlib Specifies the library handle. If this parameter is NULL, the WinLoad- 
Library function will be called, using the value of the pszProcName parameter as 
the library name. 


pszProcName Points to the null-terminated string that specifies the name of 
the procedure to be loaded. 


Return Value The return value is a pointer to the window procedure, or it is NULL if an error 
occurs. 
See Also WinDeleteProcedure, WinLoadLibrary 
HZ WinLockWindow Change 


HWND WinLockWindow( hwnd, flock) 
HWND hwnd; /x window handle «/ 
BOOL fLock; /« lock/untock flag »/ 


This function exists for compatibility with MS OS/2, version 1.1. It is not used 
in MS OS/2 1.2 or later versions. 


Changes This function is not used in MS OS/2 1.2 or later versions. 


HB WinQueryActiveWindow Change 


HWND WinQueryActiveWindow( hwnaDesktop, flock) 
HWND hwndDesktop; /»x desktop handle «/ 
BOOL fLock; /« lock/unlock flag «/ 


The WinQueryActiveWindow function retrieves the active frame window. 


Parameters hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 
Return Value The return value is the handle of the active window if the function is successful; 


it is NULL if no window was active at the time of the call or the desktop handle 
_is invalid. 


Comments If this function is called while the active window is changing, it may return 
NULL, indicating that no window was active at the time of the call. Because a 
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NULL value can also be returned if the hwndDesktop handle is invalid, the 
WinGetLastError function must be called to determine if a NULL return value 
is caused by an invalid hwndDesktop handle or because the active window was 
changing when WinQueryActiveWindow was called. 


See Also WinGetLastError, WinLockWindow, WinQueryFocus 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 
WinQueryAnchorBlock ; New 


HAB WinQueryAnchorBlock( hwnd) 
HWND hwnd; /« window handle »/ 


The WinQueryAnchorBlock function retrieves the handle of the anchor block of 
a window. 


Parameters hwnd Identifies the window whose anchor-block handle is to be returned. 


Return Value The return value is the anchor-block handle of the specified window if the func- 
tion is successful or NULL if an error occurs. 


WinQueryCapture Change 


HWND WinQueryCapture ( hwndDesktop, flock) 
HWND hwndDesktop; /« desktop handle «/ 
BOOL fLock; /» lock/unlock flag «/ 


The WinQueryCapture function returns the window handle of the window that 
has the mouse capture. 


Parameters hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop-window handle. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 


Return Value The return value is the window handle with the mouse capture if the function is 
successful; it is NULL if no window has the capture or an error occurs. 


See Also WinLockWindow, WinSetCapture 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 


WinQueryClipbrdOwner Change 


HWND WinQueryClipbrdOwner( hab, flock) 
HAB hab; /x anchor-block handle — «/ 
BOOL fLock; /» lock/untock viewer flag  «/ 


The WinQueryClipbrdOwner function retrieves the handle of the window that 
currently owns the clipboard (if any). 
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Parameters hab Identifies an anchor block. 
fLock This parameter is ignored by MS OS/2 1.2 and later versions. 
Return Value The return value is the window handle of the current clipboard owner if the 


function is successful; it is NULL if the clipboard is not owned by any window 
or if an error occurs. 


See Also WinLockWindow, WinQueryClipbrdViewer, WinSetClipbrdOwner 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 


WinQueryClipbrdViewer Change 


HWND WinQueryClipbrdViewer( hab, flock) 
HAB hab; /x anchor-block handle _ »/ 
BOOL fLock; /» lock/unlock viewer flag +/ 


The WinQueryClipbrdViewer function obtains the handle of the current clip- 
board viewer window (if any). 
Parameters hab Identifies the anchor block. 
fLock This parameter is ignored by MS OS/2 1.2 and later versions. 
Return Value The return value is the handle of the current clipboard viewer window if the 


function is successful; it is NULL if the clipboard does not have a current 
viewer window or if an error occurs. 


See Also WinLockWindow, WinQueryClipbrdOwner, WinSetClipbrd Viewer 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 
WinQueryDefinition Change 
USHORT WinQueryDefinition( hab, hProgHandle, ppib, cbMax) 
HAB hab; /x anchor-block handle »/ 
HPROGRAM hProgHandle; /« program handle »/ 
PPIBSTRUCT ppib; /«{ address of structure for program information »/ 
USHORT cbMax; /« length of buffer for program information »/ 
The WinQueryDefinition function retrieves information about a program or pro- 
gram group. 
Parameters hab Identifies the anchor block. 


hProgHandle Identifies the program or group. 


ppib_ Points to a PIBSTRUCT structure that receives the program-information 
data. If the hProgHandle parameter is a group handle, only the program-type 
and program-title fields are significant. The PIBSTRUCT structure has the fol- 
lowing form: 
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typedef struct _PIBSTRUCT { 
PROGTYPE progt; 
CHAR szTitle [MAXNAMEL+1]; 


CHAR sziconFileName [MAXPATHL+1]; 
CHAR szExecutable [MAXPATHL+1]; 
CHAR szStartupDir [MAXPATHL+1]; 
XYWINSIZE xywinInitial; 

USHORT resl; 

LHANDLE res2; 

USHORT cchEnvironmentVars; 

PCH pchEnvironmentVars; 

USHORT cchProgramParameter; 


PCH . pchProgramParameter; 
} PIBSTRUCT; 


cbMax Specifies the maximum length (in bytes) of data that can be returned 
in the data structure pointed to by the ppib parameter. If this value is zero, the 
WinQueryDefinition function returns the number of bytes in the program- 
information block. 


Return Value The return value is the length of the data actually returned in the data structure, 
or zero if an error occurs. 


If the target is a program rather than a program group, the data returned in the 
ppib parameter is in a format that can be used by the WinAddProgram function. 


Errors Use the WinGetErrorInfo function to retrieve the error value, which may be one 
of the following: 


PMERR_BUFFER_TOO_SMALL 
PMERR_INVALID_PROGRAM_HANDLE 
PMERR_MEMORY_ALLOCATION_ERR 
PMERR_MEMORY_DEALLOCATION_ERR 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


Comments The WinQueryDefinition function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfQueryDefinition function. 


See. Also PrfQueryDefinition, WinAddProgram 
Changes This function has been replaced by the PrfQueryDefinition function. 
WinQueryFocus Change 


HWND WinQueryFocus( hwndDesktop, flock) 
HWND hwndDesktop; /« desktop handle »/ 
BOOL fLock; /« lock/unlock flag «/ 


The WinQueryFocus function returns the handle of the window that currently 
has the focus. 


Parameters hwndDesktop Identifies the desktop window. This parameter can be 
HWND-_DESKTOP or the desktop window handle. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 
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Return Value The return value is a handle to the focus window or NULL if there is no focus 
window or an error occurs. 


See Also WinFocusChange, WinLockWindow, WinQueryActiveWindow, WinSetFocus 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 
WinQueryHelpInstance New 


HWND WinQueryHelpinstance ( hwndApp) 
HWND hwndApp; /» handle of application window »/ 


The WinQueryHelpInstance function retrieves the handle of the help instance 
associated with the given window. 


Parameters hwndApp Identifies a window for which the associated help instance is 
queried. 


Return Value The return value is the handle of the associated help instance if the function is 
successful; it is FALSE if an error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


HMERR_INVALID_QUERY_APP_WND 
HMERR_NO_HELP_INST_IN_CHAIN 


) 


Comments The function traces the chain of parent windows, starting with the given window, 
until it finds a frame window with an associated help instance or finds the desk- 
top. If it finds the desktop, it traces the chain of owner windows, starting with 
the given window, until it finds a frame window with an associated help instance 
or the desktop. 


See Also WinAssociateHelpInstance 

WinQueryPresParam New 

ULONG WinQueryPresParam( hwnd, id1, id2, pulld, cbBuf, pbBuf, fs) 

HWND hwnd; /« window handle »/ 

ULONG jid7; /« first parameter type to retrieve «/ 

ULONG id2; /»« second parameter type to retrieve »/ 

PULONG opulld; /« pointer to variable for parameter ID »/ 

ULONG cbBuf; /» buffer length a 

PVOID pbBuf; /« pointer to buffer for presentation parameter «/ 

USHORT fs; /« flags «/ 
The WinQueryPresParam function retrieves the presentation parameters for a 
window. 

Parameters hwnd Identifies the window that contains the presentation parameters to 


retrieve. 
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idl Identifies the first type of presentation parameter to retrieve. If both the 
idl and id2 parameters are found, id1 takes precedence and its presentation 
parameter is returned. This parameter is ignored if it is zero. | 


id2 Identifies the second type of presentation parameter to retrieve. If both 
the id1 and id2 parameters are found, idZ takes precedence and its presentation 
parameter is returned. This parameter is ignored if it is zero. 


pulld Points to the variable that receives the presentation parameter ID. 


cbBuf Specifies the length (in bytes) of the buffer pointed to by the pbBuf 
parameter. 


pbBuf Points to the buffer that receives the presentation parameter. 
fs Specifies one or more flags. These can be any combination of the following 


values: 
Value Meaning 
OPF_NOINHERIT Specifies that only the window identified by 


hwnd is to be searched for presentation parame- 
ters. If this flag is not specified, the entire 
owner-chain of the window will be searched. 


QPF_IDICOLORINDEX Specifies that the id7 parameter is a color index. 
The RGB color equivalent is returned in the 
pbBuf parameter. 

QPF_ID2COLORINDEX Specifies that the id2 parameter is a color index. 
The RGB color equivalent is returned in the 
pbBuf parameter. 


QPF_PURERGBCOLOR Specifies that the returned value should be a 
pure RGB color. 


Return Value The return value is the size (in bytes) of the presentation parameter if the func- 
tion is successful; it is NULL if no parameter was found or an error occurs. 


Comments The following parameter types are defined for MS OS/2, version 1.2: 

Value ; Meaning 

PP_FOREGROUNDCOLOR RGB foreground color 

PP_FOREGROUNDCOLORINDEX Color index of foreground 
color 

PP_BACKGROUNDCOLOR RGB background color 

PP_BACKGROUNDCOLORINDEX Color index of background 
color 

PP_HILITEFOREGROUNDCOLOR RGB color of foreground 


highlighted area 


PP_HILITEFOREGROUNDCOLORINDEX Color index of foreground 
highlighted area 


PP_HILITEBACKGROUNDCOLOR RGB color of background 
highlighted area 


PP_HILITEBACKGROUNDCOLORINDEX Color index of background 
highlighted area 
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Value . Meaning 
PP_DISABLEDFOREGROUNDCOLOR RGB foreground disabled 
color 


PP_DISABLEDFOREGROUNDCOLORINDEX Color index of foreground 
disabled color 


PP_DISABLEDBACKGROUNDCOLOR RGB color of background 
disabled color 


PP_DISABLEDBACKGROUNDCOLORINDEX Color index of background 
disabled color 


PP_BORDERCOLOR RGB color of window- 
border 
PP_BORDERCOLORINDEX Color index of window 
. border 
PP_FONTNAMESIZE Font size. 
PP_FONTHANDLE Font handle. 
See Also WinSetPresParam 
WinQueryProfileData Change 
BOOL WinQueryProfileData( hab, pszAppName, pszKeyName, pvBuf, cbBuf) . 
HAB hab; /«{ anchor-block handle a/ 
PSZ pszAppName; /« address of application name »/ 
PSZ pszKeyName; /« address of keyname »/ 
PVOID pvBuf; /» address of buffer »/ 


PUSHORT pcbBuf; 


Parameters 


Return Value 


/« address of variable with length of buffer »/ 


The WinQueryProfileData function retrieves binary data from the os2.ini file. 
The location of the data is determined by an application name and a keyname 
that are passed to the function. 


hab Identifies an anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. If pszApp- 
Name is NULL, all application names are returned. 


pszKeyName Points to a null-terminated string that contains the keyname. 

The length of the string must be less than 1024 bytes, including the null terminat- 
ing character. The keyname is case-sensitive. If pstKeyName is NULL, all key- _ 
names are returned. 


pvBuf Points to a buffer that receives the data. 


pcebBuf Points to a variable that contains the size of the buffer pointed to by 
the pvBuf parameter. When the function returns, this variable contains the actual 
number of bytes placed into the buffer. 


The return value is TRUE if the function is successful, or FALSE if an error 
occurs. 


316 WinQueryProfileData 


Comments | You can find out the size of the data prior to calling this function by calling the 
WinQueryProfileSize function. . 
The WinQueryProfileData function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfQueryProfileData function. 

See Also PrfQueryProfileData, WinQueryProfileSize, WinWriteProfileData 

Changes This function has been replaced by the PrfQueryProfileData function. 

WinQueryProfileInt Change 

SHORT WinQueryProfileInt( hab, pszAppName, pszKeyName, sError) 

HAB hab; /»* anchor-block handle »/ 

PSZ pszAppName; /» address of application name a/ 

PSZ pszKeyName; /« address of keyname a/ 


SHORT sError 


Parameters 


Return Value 


Errors 


Comments 


See Also 
Changes 


/« value returned if keyname not found «/ 


The WinQueryProfileInt function retrieves an integer from the os2.ini file. The 
location of the integer is determined by an application name and a keyname 
which are passed to this function. The WinWriteProfileString function must 
have been used previously to store the integer as a string. For example, a string 
stored as “123” would be returned as the integer 123. The string may contain a 
leading minus sign if the number is negative. 


hab Identifies the anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. 


pszKeyName Points to a null-terminated string that contains the keyname. 
The length of the string must be less than 1024 bytes, including the null terminat- 
ing character. The keyname is case-sensitive. 


_sError Specifies the error value returned if the keyname specified by the 


pszKeyName parameter cannot be found. 


The return value is the integer representation of the text string. If the keyname 
cannot be found, the error value specified by the sError parameter is returned. 


The error value may be one of the following: 


PMERR_BUFF_TOO_SMALL 
PMERR_CAN_NOT_CALL_SPOOLER 
PMERR_INVALID_PARM 
PMERR_NOT_IN_IDX 


The WinQueryProfileInt function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfQueryProfileInt function. 

PrfQueryProfileInt, WinQueryProfileData, WinWriteProfileString 


This function has been replaced by the PrfQueryProfileInt function. 


HAB hab; 
PSZ pszAppName; 
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HM WinQueryProfileSize Change 
USHORT WinQueryProfileSize (hab, pszAppName, pszKeyName, pcb) 
/« anchor-block handle »/ 
/» pointer to application name »/ 
/» pointer to keyname »/ 


PSZ pszKeyName; 
PUSHORT pcb; 


Parameters 


Return Value 


Comments 


See Also 
Changes 


/« pointer to variable with length of data »/ 


The WinQueryProfileSize function retrieves the size of the data stored at a 
specified location in the os2.ini file. The location of the data is determined by an 
application name and a keyname that are passed to this function. This function 
is typically called to determine how much memory to allocate prior to calling the 
WinQueryProfileData function. 


hab Identifies an anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. If pszApp- 
Name is NULL, the length returned in the variable pointed to by the pcb param- 
eter is the length required to contain a list of all application names for the 
pszKeyName parameter. 


pszKeyName _ Points to a null-terminated string that contains the keyname. 
The length of the string must be less than 1024 bytes, including the null terminat- 
ing character. The keyname is case-sensitive. If pszKeyName is NULL, the 
length returned in the variable pointed to by the pcb parameter is the length 
required to contain a list of all keynames. 


pcb Points to a variable that receives the length of the data. If an error 
occurs, the length is not returned. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


PMERR_CAN_NOT_CALL_SPOOLER 
PMERR_INVALID_PARM 
PMERR_NOT_IN_IDX 


The WinQueryProfileSize function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfQueryProfileSize function. 

PrfQueryProfileSize, WinQueryProfileData, WinQueryProfileString 


This function has been replaced by the PrfQueryProfileSize function. 
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M@ WinQueryProfileString | Change 


HAB hab; 

PSZ pszAppName; 
PSZ pszKeyName; 
PSZ pszError; 
PSZ pszBuf; 


USHORT WinQueryProfileString( hab, pszAppName, pszKeyName, pszError, pszBuf, cchBuf) 
’  /x anchor-block handle »/ 
/» pointer to application name »+/ 
/« pointer to keyname s/ 
/« pointer to default string »/ 
/« address of buffer for string «/ 
/« size of buffer s/ 


USHORT cchButf; 


Parameters 


Return Value 


Comments 


See Also 
Changes 


The WinQueryProfileString function retrieves a string from the os2.ini file. The 
location of the string is determined by an application name and a keyname that 
are passed to this function. 


hab Identifies an anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. If the applica- 
tion name is NULL, a list of all applications for the pszKeyName parameter is 
returned. 


pszKeyName Points to a null-terminated string that contains the keyname. 
The length of the string must be less than 1024 bytes, including the null terminat- 
ing character. If this parameter is NULL, all keynames are enumerated. The 
keyname is case-sensitive. 


pszError Points to a null-terminated string that is placed in the buffer pointed 
to by the pszBuf parameter if the key is not found. 


pszBuf Points to a buffer that will receive the null-terminated string. 
cchBuf Specifies the length of the buffer pointed to by the pszBuf parameter. 
If the retrieved string is longer than this value, it is truncated. 


The return value is the number of characters in the buffer pointed to by the 
pszBuf parameter. 


The WinQueryProfileString function provides compatibility with MS OS/2 1.1 
and earlier versions. Applications intended exclusively for MS OS/2 1.2 and 
later versions should use the PrfQueryProfileString function. 


PrfQueryProfileString, WinWriteProfileString 


This function has been replaced by the PrfQueryProfileString function. © 


™@ WinQueryProgramTitles Change 
USHORT WinQueryProgramTitles (hab, hGroup, paproge, cbBuf, pcTitles) 


HAB hab; 


/« handle of anchor block x/ 


HPROGRAM AGroup; /« handle of group »/ 
PPROGRAMENTRY paproge; /« pointer to array of structures for program info. »/ 


USHORT cbBuf; 
PUSHORT pcTitles; 


/« length of buffer for array of structures x/ 
/« pointer to variable for number of titles »/ 


The WinQueryProgramTitles function obtains information about programs 
within a specified program group. 


Parameters 


Return Value 


Errors 


Comments 


See Also 


Changes 
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You can use the WinQueryProgramTitles function to find out the number of 
entries within a group. If you pass a buffer of zero bytes, the function returns the 
total number of entries within the group. 


The list of returned program entries may contain group handles. Group handles 
allow the tree structure to be built by the caller; however, this function returns 
information from only one level of the tree structure. 


WinQueryProgramTitles can be used to retrieve the program title, by specifying 
a program handle in the hGroup parameter. In this case, the buffer will contain 
an entry for only one program. 


hab Identifies the anchor block. 


hGroup Identifies the group for which information is returned. This handle is 
either the handle of a program group or SGH_ROOT for the root group. 


Paproge Points to an array of PROGRAMENTRY structures where the pro- 
gram information is returned. The PROGRAMENTRY structure has the follow- 
ing form: 
typedef struct _PROGRAMENTRY { 

HPROGRAM hprog; 

PROGTYPE progt; 


CHAR szTitle [MAXNAMEL+1] ; 
} PROGRAMENTRY; 


cbBuf Specifies the total length (in bytes) of the area pointed to by the 
paproge parameter. Values of cbBuf less than the size of a PROGRAMENTRY 
structure are invalid. 


pcTitles Points to a variable that receives the count of the available titles. If 
the hGroup parameter is SGH_ROOT and the buffer length specified in the 
cbBuf parameter is too small to hold all the titles, the return value is zero, none 
of the titles are copied to the buffer, and pcTitles contains the number of avail- 
able titles. If hGroup is a program handle, both the return value and pcTitles are 
the number of available handles. 


The return value is the number of available titles, or zero if an error occurs. 


Use the WinGetErrorInfo function to retrieve the error value, which may be one 
of the following: 


PMERR_BUFFER_TOO_SMALL 
PMERR_INVALID_GROUP_HANDLE 
PMERR_INVALID_TARGET_HANDLE 
PMERR_NOT_CURRENT_PL_VERSION 
PMERR_NOT_IN_IDX 


The WinQueryProgramTitles function provides compatibility with MS OS/2 1.1 
or earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfQueryProgramTitles function. 
PrfQueryProgramTitles, WinAddProgram 


This function has been replaced by the PrfQueryProgramTitles function. 
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@ WinQuerySessiontTitle New 
USHORT WinQuerySessionritle ( hab, usSession, pszTitle, cbTitle) 
HAB hab; /« anchor-block handle »/ 
USHORT usSession; /» screen session »/ 
PSZ pszTitle; /» pointer to buffer for title »/ 
USHORT cbTitle; /« buffer length »/ 


The WinQuerySessionTitle function retrieves the title under which a specified 
application was started or added to the Task List. 
Parameters hab Identifies the anchor block. 


usSession Specifies the screen session. For MS OS/2 version 1.2, this value 
may be 0 or 1; 0 means the screen session of the caller. 


pszTitle Points to the buffer that receives the null-terminated string that 
specifies the application’s title. 


cbTitle Specifies the length (in bytes) of the buffer pointed by pszTitle. If the 
title string is longer than this length, the title will be truncated. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


PMERR_INVALID_SESSION_ID 


Comments The length of the title is guaranteed not to exceed MAXNAMEL bytes, plus one 
for the null-terminating character. (MAXNAMEL is defined in the MS OS/2 
include files.) 


Example This example calls WinQuerySessionTitle to retrieve the application’s title, and 
then sets the title bar of the frame window to that title: 
CHAR szTitle[MAXNAMEL + 1]; 


WinQuerySessionTitle(hab, 0, szTitle, sizeof(szTitle)); 
WinSetWindowText (hwndFrame, szTitle) ; 


See Also WinSetWindowText 


M@ WinQuerySwitchEntry New 


USHORT WinQuerySwitchEntry ( hSwitch, pswct!/) 
HSWITCH ASwitch; /« item handle »/ 
PSWCNTRL psweti; /« point to structure with item data »/ 


The WinQuerySwitchEntry function obtains a copy of the Task List data for a 
specific application. 
Parameters hSwitch Identifies the Task List item. 


pswetl Points to the SWCNTRL data structure that contains information about 
the specified Task List item. The SWCNTRL structure has the following form: 


Return Value 


See Also 
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typedef struct _SWCNTRL { 
HWND hwnd; 
HEWND hwndIcon; 
HPROGRAM hprog; 
USHORT idProcess; 
USHORT idSession; 


UCHAR uchVisibility; 
UCHAR fbJump; 
CHAR szSwtitle [MAXNAMEL+1]; 
BYTE fReserved; 
} SWCNTRL; 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


PMERR_INVALID_SWITCH_HANDLE 
WinQuerySwitchHandle 


WinQuerySwitchHandle New 


HSWITCH WinQuerySwitchHandle( hwnd, pidProcess) 


HWND hwnd; 
PID pidProcess; 


Parameters 


Return Value 
Comments 


Example 


See Also 


/» window handle — «/ 
/« process identifier »/ 


The WinQuerySwitchHandle function retrieves the handle of the Task List item 
of an application. 


hwnd Identifies the frame window of the application. This parameter may be 
zero if the process identifier is specified in the pidProcess parameter. 
pidProcess Specifies the process identifier. This parameter may be zero if the 
window handle is specified in the hwnd parameter. 


The return value is the Task List handle for the specified application if the func- 
tion is successful or NULL if an error occurs. 


If both a window handle and a process identifier are supplied, they both must 
apply to the same application. 


This example calls WinQuerySwitchHandle to get the Task List handle of a 
frame window, and then calls WinQuerySwitchEntry to retrieve information 
about that application: 


HSWITCH hswitch; 
SWCNTRL swctl; 


hswitch = WinQuerySwitchHandle(hwndFrame, 0); 
WinQuerySwitchEntry (hswitch, &swcetl); 


WinQuerySwitchEntry 
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USHORT WinQuerySwitchList( hab, pswbik, cbswbik) 


HAB hab; 


PSWBLOCK pswbik; 


HZ WinQuerySwitchList New 
/x anchor-block handle »/ 
/« pointer to structure for items «/ 
/»« structure length x/ 


USHORT cbswbik; 


Parameters 


Return Value 


The WinQuerySwitchList function obtains information about the items in 
the Task List (the list of programs running in the system). 


hab Identifies the anchor block. 


pswblk Points to SWBLOCK structure that receives a description of all the 
items in the Task List. The SWBLOCK structure has the following form: 
typedef struct _SWBLOCK { : 

USHORT cswentry; 


SWENTRY aswentry [1]; 
} SWBLOCK; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
cbswblk — Specifies the size (in bytes) of the SWBLOCK structure. This param- 
eter may be zero to retrieve only the number of Task-list items. 


The return value is the current number of items in the Task List if the function 
is successful or zero if an error occurs. 


Comments The SWBLOCK structure contains an array of SWENTRY structures. The first 
array contains information about the Task List window. The second array con- 
tains information about the first program in the Task List. 

Example This example calls WinQuerySwitchList to determine the number of items in 
the Task List, allocates memory for the required buffer, and calls WinQuery- 
SwitchList again to fill the buffer with the information about each program in the 
Task List: 

USHORT cbItems, cbBuf; 

PSWBLOCK pswblk;. 

SEL sel; 

ebItems = WinQuerySwitchList (hab, NULL, 0); /* gets num. of items */ 
cbBuf = (cbIitems * sizeof(SWENTRY)) + sizeof (HSWITCH) ; 
DosAllocSeg(cbBuf, &sel, SEG_NONSHARED) ; /* allocates buffer */ 
pswblk = MAKEP(sel, O); 

WinQuerySwitchList (hab, pswblk, cbBuf); /* gets struct. array */ 

See Also WinQuerySwitchEntry 

—M WinQuerySysModalWindow Change 
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HWND WinQuerySysModalWindow ( hwndDesktop, flock) 
HWND hwndDesktop;' /«handle of the desktop «/ 


BOOL fLock; 


Parameters 


/« lock/uniock flag a/ 


The WinQuerySysModalWindow function returns the current system modal win- 
dow. 


hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


Return Value 


See Also 
Changes 
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fLock This parameter is ignored by MS OS/2 1.2 and later versions. 


The return value is the handle of the current system modal window. If there is 
none, the return value is NULL. 


WinLockWindow, WinSetSysModalWindow 


The fLock parameter is ignored by MS OS/2 1.2 and later versions. 


WinQuerySysValue Change 


LONG WinQuerySysValue ( hwndDesktop, iSysValue) 
HWND hwndaDesktop; /« handle of desktop »/ 


SHORT iSysValue; 


Parameters 


Return Value 


Comments 


/« system value to retrieve «/ 
The WinQuerySysValue function retrieves a specified system value. 


hwndDesktop. Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


iSysValue Specifies the system value. 


The return value is the system value if the function is successful, or zero if an 
error occurs. 


The system values can be any of the following values: 


Value Meaning 

SV_CMOUSEBUTTONS Specifies the number of mouse buttons: 1, 
2, or 3. 

SV_MOUSEPRESENT Specifies whether the mouse is present. A 
value of TRUE means the mouse is present. 

SV_SWAPBUTTON Specifies whether the mouse buttons are 


swapped. A value of TRUE means the 
mouse buttons are swapped. 


SV_CXDBLCLK Specifies the horizontal spacing for a mouse 
double-click. When the horizontal distance 
between two mouse clicks is less than this 
value, the horizontal spacing requirement 
for considering two mouse clicks a double- 
click is met. 


SV_CYDBLCLK Specifies the vertical spacing for a mouse 
double-click. When the vertical distance 
between two mouse clicks is less than this 
value, the vertical spacing requirement for 
considering two mouse clicks a double-click 
is met. 


SV_DBLCLKTIME Specifies the mouse double-click time, in 
milliseconds. When the time between two 
mouse clicks is less than this value, the tem- 
poral requirement for considering two 
mouse clicks a double-click is met. 
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Value 


SV_CXSIZEBORDER 


Meaning 


Specifies the number of pels along the x-axis 


SV_CYSIZEBORDER 


SV_ALARM 


SV_CURSORRATE 


SV_FIRSTSCROLLRATE 


SV_SCROLLRATE 


SV_NUMBEREDLISTS 
SV_ERRORFREQ 


SV_NOTEFREQ 


SV_WARNINGFREQ 


SV_ERRORDURATION 
SV_NOTEDURATION 


SV_WARNINGDURATION 


SV_CXSCREEN 
SV_CYSCREEN 
SV_CXVSCROLL 
SV_CYHSCROLL 


SV_CXHSCROLLARROW 


in a window-sizing border. 


Specifies the number of pels along the y-axis 
in a window-sizing border. 


Specifies whether a call to the WinAlarm 
function generates a sound. A value of 
TRUE means sound is generated. 


Specifies the rate at which the cursor blinks, 
in milliseconds. The blink rate is the time 
that the cursor remains visible or invisible. 
Twice this value is the time the cursor takes 
to cycle from visibility to invisibility and 
back. 


Specifies the delay (in milliseconds) between 
clicking and holding down the mouse button 
(when the mouse pointer is on a scroll 
arrow or scroll bar) and the beginning of 
scroll-bar autorepeat activity. 


Specifies the delay (in milliseconds) between 
scroll-bar autorepeat events. 


Reserved. 


Specifies the frequency (in hertz) of a 
WinAlarm function WA_ERROR sound. 


Specifies the frequency (in hertz) of a 
WinAlarm function WA_NOTE sound. 


Specifies the frequency (in hertz) of a 
WinAlarm function WA_WARNING 
sound. 


Specifies the duration (in milliseconds) of a 
WinAlarm function WA_ERROR sound. 


Specifies the duration (in milliseconds) of a 
WinAlarm function WA_NOTE sound. 


Specifies the duration (in milliseconds) of a 
WinAlarm function WA_WARNING 
sound. 


Specifies the number of pels along the 
screen’s x-axis. 


Specifies the number of pels along the 
screen’s y-axis. 


Specifies the number of pels along the x-axis 
of a vertical scroll bar. 


Specifies the number of pels along the y-axis 
of a horizontal scroll bar. 


Specifies the number of pels along the x-axis 
of a horizontal scroll arrow. 


Value 


SV_CYVSCROLLARROW 
SV_CXBORDER 
SV_CYBORDER 
SV_CXDLGFRAME 
SV_CYDLGFRAME 
SV_CYTITLEBAR 
SV_CXHSLIDER 
SV_CYVSLIDER 
SV_CXMINMAXBUTTON 
SV_CYMINMAXBUTTON 
SV_CYMENU 
SV_CXFULLSCREEN 


SV_CYFULLSCREEN 


SV_CXICON 
SV_CYICON 
SV_CXPOINTER 
SV_CYPOINTER 


SV_DEBUG 


SV_CURSORLEVEL 


SV_POINTERLEVEL 
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Meaning 


Specifies the number of pels along the y-axis 
of a vertical scroll arrow. 


Specifies the number of pels along the x-axis 
of a window border. 


Specifies the number of pels along the y-axis 
of a window border. 


Specifies the number of pels along the x-axis 
of a dialog-box frame. 


Specifies the number of pels along the y-axis 
of a dialog-box frame. 


Specifies the number of pels along the y-axis 
of a title-bar window. 


Specifies the number of pels along the x-axis 
of a horizontal scroll-bar slider. 


Specifies the number of pels along the y-axis 
of a vertical scroll-bar slider. 


Specifies the width (in pels) of a minimize 
or maximize button. 


Specifies the height (in pels) of a minimize 
or maximize button. 


Specifies the height (in pels) of a menu. 


Specifies the number of pels along the x-axis 
of the client window of a maximized frame 
window. 


Specifies the number of pels along the y-axis 
of the client window of a maximized frame 
window. 


Specifies the number of pels along an icon’s 
X-axis. 


Specifies the number of pels along an icon’s 
y-axis. 


Specifies the number of pels along the 
mouse pointer’s x-axis. 


Specifies the number of pels along the 
mouse pointer’s y-axis. 


Specifies whether a debugging version of 
OS/2 is being run. This value is TRUE if a 
debugging version is being run. 


Specifies the cursor display count. The cur- 
sor is visible only when the display count is 
zero. 


Specifies the mouse-pointer display count. 
The mouse is visible only when the display 
count is zero. 
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Value Meaning 


SV_TRACKRECTLEVEL Specifies the tracking-rectangle display 
count. The tracking rectangle is visible only 
when the display count is zero. 


SV_CTIMERS Specifies the number of available timers. 

SV_CXBYTEALIGN Specifies a horizontal alignment that is more 
efficient for the device driver. 

SV_CYBYTEALIGN Specifies a vertical alignment that is more 
efficient for the device driver. 

SV_EXTRAKEYBEEP Specifies whether beep is turned on for 
extended keys (keys not on an IBM PS/2 or 
compatible keyboard). 

. SV_SETLIGHTS Specifies if the system controls the keyboard 

indicator lights. 

SV_LINSERTMODE Specifies if insert mode is on or off for 


entry-field controls. | 
SV_.MENUROLLDOWNDELAY Specifies the delay for menu roll down. 


SV_MENUROLLUPDELAY Specifies the delay for menu roll up. 
SV_ALTMNEMONIC Specifies if the Alt key is allowed as a 
mnemonic. 


SV_TASKLISTMOUSEACCESS Specifies if the task list can be accessed by 
the right mouse button. 


SV_CSYSVALUES Specifies the number of system values. 
See Also WinSetSys Value 


Changes The following system values have been added: 


SV_EXTRAKEYBEEP 
SV_SETLIGHTS 
SV_INSERTMODE 
SV_MENUROLLDOWNDELAY 
SV_MENUROLLUPDELAY: 
SV_ALTMNEMONIC 
SV_TASKLISTMOUSEACCESS 


@ WinQueryTaskSizePos New 


USHORT WinQueryTaskSizePos( hab, usSession, pswp) 

HAB hab; /» anchor-block handle s/ 
USHORT usSession; /x screen session s/ 
PSWP pswp; /« pointer to structure for defaults »/ 


The WinQueryTaskSizePos function retrieves the default size, position, and 
status for the first frame window of a newly started application. 


Parameters hab Identifies the anchor block. 
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usSession Specifies the screen session. For MS OS/2 version 1.2, this value 
can be 0 or 1; 0 specifies the screen session of the caller. 


pswp Points to the SWP structure that receives the default size, position, and 
status for the first frame window of the application. The SWP structure has the 
following form: 


typedef struct _SWP { 


USHORT fs; 
SHORT cy; 
SHORT cx; 
SHORT y; 
SHORT x; 


HWND hwndInsertBehind; 
HWND hwnd; 
} SWP; 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


PMERR_INVALID_SESSION_ID 
See Also WinQueryWindowPos 


WinQueryWindow Change 


HWND WinQueryWindow( hwnd, cmd, flock) 
HWND hwna; /« handle of the window »/ 
SHORT cmd; /« which window to retrieve »/ 
BOOL fLock; /» lock/unlock flag »/ 


The WinQueryWindow function retrieves the handle of a window that has a 
specified relationship to a specified window. 


If WinQueryWindow is used to enumerate windows of other threads, it is not 
guaranteed that all the windows are enumerated, because the Z ordering of the 
windows may change during the enumeration. The WinGetNextWindow function 
must be used for this purpose. 


Parameters hwnd Identifies a window. The window handle retrieved is relative to this win- 
dow, based on the value in the cmd parameter. 


cmd _ Specifies which window to retrieve. The following are the possible 


values: 
Value Meaning 
QW_NEXT Next window in Z order (window below). 
QW_PREV Previous window in Z order (window above). 
QW_TOP Topmost child window. 
QW_BOTTOM Bottommost child window. 
QW_OWNER Owner of the window. 
QW_PARENT Parent of window; HWND_OBJECT if object 


window. 
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Value Meaning 

QW_NEXTTOP Next main window in the enumeration order 
defined for the ALT+ESCAPE function of the user 
interface. 

QW_PREVTOP Previous main window, in the enumeration order 


defined by QW_NEXTTOP. 


QW_FRAMEOWNER Returns the owner of hwnd, normalized so that it 
shares the same parent as hwnd. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 


Return Value The return value is the handle of the window related to the window identified by 
the hwnd parameter. 


See Also WinGetNextWindow, WinLockWindow 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 
WinQueryWindowLockCount Change 


SHORT WinQueryWindowLockCount( hwnd) 
HWND hwnd; /« window handle »«/ 


This function exists for compatibility with MS OS/2 version 1.1. It is not used in 
MS OS/2 1.2 or later versions. 


Changes . This function is not used in MS OS/2 1.2 or later versions. 
WinRegisterClass Change 
BOOL WinRegisterClass (hab, pszClassName, pfnWndProc, fiStyle, chbWindowData) 

HAB hab; - /« handle of anchor block »/ 

PSZ pszClassName; /« points to class name »/ 

PFNWP pfnWndProc; /» address of window procedure +/ 

ULONG /iStyle; /« window-style flags »/ 


USHORT cbWindowData; /«{ amount of reserved data »/ 


The WinRegisterClass function registers a window class. 


When an application registers a private class with the window procedure in a 
dynamic-link library, the application must resolve the window-procedure address 
before calling WinRegisterClass. 


Private classes are deleted when the process that registers them terminates. 


Parameters hab Identifies the anchor block. 


pszClassName Points to a null-terminated string that specifies the name of the 
window class. The string can be either a name specified by an application or the 
name of one of the following preregistered classes: 


pfnWndProc 


Class 


WC_BUTTON 


WC_COMBOBOX 
WC_ENTRYFIELD 


WC_FRAME 
WC_LISTBOX 


WC_MLE 
WC_MENU 


WC_SCROLLBAR 
WC_STATIC 


WC_TITLEBAR 
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Description 

A button control, including push buttons, radio 
buttons, check boxes, and user buttons. 

A combination entry-field and list-box control. 


An entry-field control that allows single-line text 
editing. 


A standard frame window. 


A list box that displays items in a list that can be 
scrolled. 


A multiple-line entry field. 


A menu, including the menu bar and the menus 
that can selected from it. 


A scroll bar that allows a user to scroll the con- 
tents of a window. 


A static control that displays text, icon, or bitmap 
data. 


A title-bar control that displays the title of a win- 
dow across the top of the frame and also allows the 
user to drag the frame window to a new location. 


Points to the window procedure. This value can be NULL if the 


application does not provide a window procedure. An application written in a 
language that does not allow the system to call the application’s window pro- 
cedure (for example, COBOL or FORTRAN) should also use NULL for this 
parameter. For more information, see WinGetDlgMsg. 


fiStyle Specifies the default window style, which can be any of the standard 
CS class styles, and any class-specific window styles that may be defined. These 
styles can be augmented when a window of this class is created. A public win- 
dow class is created if the CS_PUBLIC style is specified; otherwise, a private 
class is created. Public classes are available from any process for creating a win- 
dow. Private classes are available only to the registering process. 


The following list describes the standard classes: 
Style Meaning 


CS_CLIPCHILDREN Sets the WS_CLIPCHILDREN style for win- 


dows created using this class. 


Sets the WS_CLIPSIBLINGS style for windows 
created using this class. 


CS_CLIPSIBLINGS 


CS_FRAME 


Identifies windows created using this class as 
frame windows. 
CS_HITTEST Directs the system to send a WM_HITTEST 


message to a window of this class whenever the 
mouse moves in the window. 


Directs the system to send a WM_MOVE mes- 
sage to the window whenever the window 
moves. 


CS_MOVENOTIFY 
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Return Value 


Example 


See Also 


Changes 


WinReleasePS 


Style Meaning 

CS_PARENTCLIP Sets the WS_PARENTCLIP style for windows 
created using this class. 

CS_PUBLIC Creates a public window class. 

CS_SAVEBITS Sets the WS_SAVEBITS style for windows 
created using this class. 

CS_SIZEREDRAW Directs the system to invalidate the entire win- 
dow whenever the size of the window changes. 

CS_SYNCPAINT Sets the WS_SYNCPAINT style for windows 


created using this class. 


cbWindowData _ Specifies the number of bytes of storage reserved for use by 
applications for each window created of this class. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


This example calls WinRegisterClass to register a class or returns FALSE if an 
error occurs. 


HAB hab; 


CHAR szClassName[(} = "Generic"; /* window class name a/ 
if (!WinRegisterClass (hab, /* anchor-block handle a/ 
szClassName, * class name */ 
GenericWndProc, /* window procedure */ 
OL, /* window style a/ 


0)) 7* amount of reserved memory */ 
return (FALSE); 


WinGetDlgMsg, WinQueryClassInfo, WinQueryClassName, WinQuery- 
WindowPtr, WinQueryWindowULong, WinQueryWindowUShort 


The constants WC_COMBOBOX and WC_MLE have been added to the list of 
preregistered classes. 


Correction 


BOOL WinReleasePS(hps) 
HPS hps; /« presentation-space handle «/ 


Parameters 


Return Value 


Comments 


The WinReleasePS function releases a cached presentation space obtained by 
using the WinGetClipPS, WinGetPS, or WinGetScreenPS function. 


Only a cached presentation space can be released using this function. The 
presentation space is returned to the cache for reuse. The presentation-space 
handle should not be used following this function. 


hps Identifies the cached presentation space to release. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


Before an application terminates, it must call WinReleasePS to release any 
cached presentation spaces obtained. 


Example 


See Also 


Corrections 
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This example processes an application-defined message (IDM_FILL). It calls 
WinGetPS to get a presentation space to the entire window. It gets the dimen- 
sions of the current window, fills the window, and calls WinReleasePS to release: 
the presentation space. 


case IDM_FILL: 


hps = WinGetPS (hwnd) ; /* gets ps for entire window */ 
WinQueryWindowRect (hwnd, &rcl); /* gets window dimensions */ 
WinFillRect(hps, &rcl, CLR_WHITE); /* clears entire window a/ 
WinReleasePS (hps) ; /* releases ps a/ 


WinGetClipPS, WinGetPS, WinGetScreenPS 


The WinReleasePS function is used to release any cached presentation space, 
including those created with the WinGetClipPS and WinGetScreenPS functions. 


WinRemovePresParam 


BOOL WinRemovePresParam( hwnd, id) 
/« window handle s/ 
/« presentation parameter to remove »/ 


HWND hwnd; 
ULONG ja; 


Parameters 


New 


The WinRemovePresParam function removes a presentation parameter. 


hwnd Identifies the window that contains the presentation parameters to 
remove. 


id 


Identifies the presentation parameter to remove. It may be one of the fol- 
lowing values: 


Value 


PP_FOREGROUNDCOLOR 
PP_FOREGROUNDCOLORINDEX 


PP_BACKGROUNDCOLOR 
PP_BACKGROUNDCOLORINDEX 


PP_HILITEFOREGROUNDCOLOR 


PP_LHILITEFOREGROUNDCOLORINDEX 


PP_HILITEBACKGROUNDCOLOR 


PP_HILITEBACKGROUNDCOLORINDEX 


PP_DISABLEDFOREGROUNDCOLOR 


PP_DISABLEDFOREGROUNDCOLORINDEX 


Meaning 


RGB foreground color 


Color index of fore- 
ground color 


RGB background color 


Color index of back- 
ground color 


RGB color of foreground 
highlighted area 


Color index of fore- 
ground highlighted area 


RGB color of back- 
ground highlighted area 


Color index of back- 
ground highlighted area 


RGB foreground disabled 
color 


Color index of fore- 


_ ground disabled color 
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Return Value 


Comments When a presentation parameter is removed, a WMW_PRESPARAMCHANGED 
message is sent to all windows owned by the window calling the WinSetPres- 
Param function. 

See Also WinQueryPresParam, WinSetPresParam 

WinSetPresParam New 

BOOL WinSetPresParam( hwnd, id, cbParam, pbParam) 

HWND hwnd: /» window handle »/ 

ULONG id; /« presentation parameter »/ 

ULONG cbParam; /« presentation-parameter size »/ 


PVOID pbParam; 


Parameters 


WinRemovePresParam 


Value Meaning 


RGB color of back- 
ground disabled color 


PP_DISABLEDBACKGROUNDCOLOR 


PP_DISABLEDBACKGROUNDCOLORINDEX Color index of back- 


ground disabled color 


PP_BORDERCOLOR RGB color of window 


border 
PP_BORDERCOLORINDEX Color index of window 

border 
PP_FONTNAMESIZE Font size 


PP_FONTHANDLE Font handle 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


/« pointer to presentation parameter «/ 


The WinSetPresParam function sets a presentation parameter. 


hwnd 


id Identifies the presentation parameter to set. It may be one of the following 


values: 
Value 


PP_FOREGROUNDCOLOR 
-PP_FOREGROUNDCOLORINDEX 


PP_BACKGROUNDCOLOR 
PP_BACKGROUNDCOLORINDEX 


PP_HILITEFOREGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLORINDEX 


PP_HILITEBACKGROUNDCOLOR 


Identifies the window that contains the presentation parameters to set. 


Meaning 


RGB foreground color 


Color index of foreground 
color 


RGB background color 


Color index of background 
color 


RGB color of foreground 
highlighted area 


Color index of foreground 
highlighted area 


RGB color of background 
highlighted area 


Return Value 


Comments 


See Also 


Value 


PP_HILITEBACKGROUNDCOLORINDEX 


PP_DISABLEDFOREGROUNDCOLOR 


PP_DISABLEDFOREGROUNDCOLORINDEX 


PP_DISABLEDBACKGROUNDCOLOR 


PP_DISABLEDBACKGROUNDCOLORINDEX 


PP_BORDERCOLOR 


PP_BORDERCOLORINDEX 


PP_FONTNAMESIZE 
PP_FONTHANDLE 


WinSetSysColors 


Meaning 
Color index of background 
highlighted area 


RGB foreground disabled 
color 

Color index of foreground 
disabled color 

RGB color of background 
disabled color 


Color index of background 
disabled color 


RGB color of window 
border 


Color index of window 
border 


Font size 
Font handle 


cbParam Specifies the length (in bytes) of the buffer pointed to by the 


pbParam parameter. 


pbParam Points to the buffer that contains the presentation parameter. 


The return value is TRUE if the function is successful or FALSE if an error 


occurs. 
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When a presentation parameter is set, a WM_PRESPARAMCHANGED mes- 
sage is sent to all windows owned by the window calling the WinSetPresParam 


function. 


WinQueryPresParam, WinRemovePresParam 


HM WinSetSysColors 


Correction 


BOOL WinSetSysColors( hwndDesktop, flOptions, flFormat, cirFirst, ccir, pcir) 


HWND hwndDesktop; 


ULONG flOptions; 
ULONG flFormat; 
COLOR clrFirst; 
ULONG cclir 
PCOLOR perlr 


/« handle of the desktop 
/» color options 

/« format options 

/« first color to set 


/» number of colors to set 


/« address of color definitions «/ 


The WinSetSysColors function sets system color values. This function sends a 
WM_SYSCOLORCHANGE message to all main windows in the system to indi- 
cate that the colors have changed. When this message is received, applications 
that depend on the system colors can query the new color values by using the 


WinQuerySysColor function. 
After the WM_SYSCOLORCHANGE messages are sent, all windows in the 


system are invalidated so that they will be redrawn with the new system colors. 


WinSetSysColors does not write any system color changes to the os2.ini file. 
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Parameters hwndDesktop Identifies the desktop window. This parameter can be 


HWND_DESKTOP or the desktop window handle. 


flOptions Specifies the following options: 
Value Meaning 


LCOL_PURECOLOR Indicates that color dithering should not be used to 
create colors not available in the physical palette. 
If this option is set, only pure colors will be used 


and no dithering will be done. 


LCOL_RESET Indicates that the system colors are all to be reset 
to default before processing the remainder of the 


data in this function. 


fiFormat Specifies the format of entries in the table, as follows: 
Value Meaning 


LCOLF_CONSECRGB Array of RGB values that correspond to color 


indexes. Each entry is 4 bytes. 


LCOLF_INDRGB Array of (index, RGB) values. Each pair of entries 


is 8 bytes (4 bytes index and 4 bytes color value). 


clrFirst Specifies the starting system color index (this parameter is only 
relevant for the LCOLF_CONSECRGB format). The following system color 
indexes are defined (each successive index is one larger than its predecessor): 


Value Meaning 


SYSCLR_BUTTONLIGHT 
SYSCLR_BUTTONMIDDLE 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONDEFAULT 
SYSCLR_TITLEBOTTOM 
SYSCLR_SHADOW 
SYSCLR_ICONTEXT 


SYSCLR_DIALOGBACKGROUND 


SYSCLR_HILITEFOREGROUND 
SYSCLR_HILITEBACKGROUND 


SYSCLR_INACTIVETITLETEXTBGND 
SYSCLR_ACTIVETITLETEXTBGND 


SYSCLR_INACTIVETITLETEXT 
SYSCLR_ACTIVETITLETEXT 
SYSCLR_OUTPUTTEXT 
SYSCLR_WINDOWSTATICTEXT 
SYSCLR_SCROLLBAR 
SYSCLR_BACKGROUND 
SYSCLR_ACTIVETITLE 
SYSCLR_INACTIVETITLE 


Light button 

Middle button 

Dark button 

Default button 

Bottom title 

Shadow 

Icon text 

Dialog-box background 
Foreground hilight 
Background hilight 

Inactive title-text background 
Active title-text background 
Inactive title-text 

Active title-text 

Output text 

Static text 

Scroll bar 

Screen background 

Title bar of active window 


Title bar of inactive window 


Return Value 


See Also 


Corrections 
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Value Meaning 
SYSCLR_MENU Menu background 
SYSCLR_WINDOW Window background 
SYSCLR_WINDOWFRAME Window border line 
SYSCLR_MENUTEXT Menu text 
SYSCLR_WINDOWTEXT Window text 
SYSCLR_TITLETEXT Title text 
SYSCLR_ACTIVEBORDER Border fill of active window 
SYSCLR_INACTIVEBORDER Border fill of inactive window 
SYSCLR_APPWORKSPACE Background of certain main win- 
dows 
SYSCLR_HELPBACKGROUND Background of help panels 
SYSCLR_HELPTEXT Help text 
SYSCLR_HELPHILITE Highlight of help text 


cclr Specifies the number of elements supplied in pcir. This parameter may be 
zero if, for example, the color table is merely to be reset to the default. For 
LCOLF_INDRGB, this parameter must be an even number. The constant 
SYSCLR_CSYSCOLORS is set to the total number of system colors. 


pcelr Specifies the start address of the application data area containing the 
color-table definition data. The format depends on the value of the flFormat 
parameter. Each color value is a 4-byte integer. The low byte is the blue intensity 
value (Ox000000FF), the second byte is the green intensity value (OxOOO0FFO0), 
and the third byte is the red intensity value (OxOOFF0000). The intensity for each 
color may range between 0 and 255. 


The return value is TRUE if the function is successful or FALSE if an error 
occurs. 


WinQuerySysColor 
The following system colors have been added: 


SYSCLR_BUTTONLIGHT 
SYSCLR_BUTTONMIDDLE 
SYSCLR_BUTTONDARK 
SYSCLR_BUTTONDEFAULT 
SYSCLR_TITLEBOTTOM 
SYSCLR_SHADOW 
SYSCLR_ICONTEXT 
SYSCLR_DIALOGBACKGROUND 
SYSCLR_HILITEFOREGROUND 
SYSCLR_HILITEBACKGROUND 
SYSCLR_INACTIVETITLETEXTBGND 
SYSCLR_ACTIVETITLETEXTBGND 
SYSCLR_LINACTIVETITLETEXT 
SYSCLR_ACTIVETITLETEXT 
SYSCLR_OUTPUTTEXT 


The system colors were listed alphabetically instead of by numerical order. The 
numerical order is important because it is used to determine the starting color to 
change when LCOLF_CONSECRGB is specified for fiFormat. 
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WinSetSysValue Change 


BOOL WinSetSysValue ( hwndDesktop, iSysValue, IValue) 
HWND hwndaDeskiop; /x handle of desktop window »«/ 
SHORT iSysValue; /« system value to change ~_«/ 
LONG /Value; /« new system value »/ 


The WinSetSysValue function sets the system value. 


Parameters hwndDesktop Identifies the desktop window. This parameter can be 
HWND_DESKTOP or the desktop window handle. 


iSysValue Specifies the system value. For a complete list of possible system 
values, see the following “Comments” section. 


lValue Specifies the system value. Durations are in milliseconds. Frequencies 
are in hertz; valid values are 0x0025 through 0x7FFF. 


Return Value The return value is TRUE if the system value is successfully set. Otherwise, it is 
FALSE, indicating that an error occurred. 


Comments The system values can be any of the following values: 

Value Meaning 

SV_CMOUSEBUTTONS Specifies the number of mouse buttons: 1, 
2, or 3. 

SV_MOUSEPRESENT Specifies whether the mouse is present. A 
value of TRUE means the mouse is 
present. 

SV_SWAPBUTTON Specifies whether the mouse buttons are 


swapped. A value of TRUE means the 
mouse buttons are swapped. 


SV_CXDBLCLK Specifies the horizontal spacing for a 
mouse double-click. When the horizontal 
distance between two mouse clicks is less 
than this value, the horizontal spacing 
requirement for considering two mouse 
clicks a double-click is met. 


SV_CYDBLCLK Specifies the vertical spacing for a mouse 
double-click. When the vertical distance 
between two mouse clicks is less than this 
value, the vertical spacing requirement for 
considering two mouse clicks a double- 
click is met. 


SV_DBLCLKTIME Specifies the mouse double-click time, in 
milliseconds. When the time between two 
mouse clicks is less than this value, the 
temporal requirement for considering two 
mouse clicks a double-click is met. 


SV_CXSIZEBORDER Specifies the number of pels along the 
x-axis in a window-sizing border. 
SV_CYSIZEBORDER Specifies the number of pels along the 


y-axis in a window-sizing border. 
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Value Meaning 


SV_ALARM Specifies whether a call to the WinAlarm 
function generates a sound. A value of 
TRUE means sound is generated. 


SV_CURSORRATE Specifies the rate at which the cursor 
blinks, in milliseconds. The blink rate is 
the time that the cursor remains visible or 
invisible. Twice this value is the time the 
cursor takes to cycle from visibility to 
invisibility and back. 


SV_FIRSTSCROLLRATE Specifies the delay (in milliseconds) 
between clicking and holding down the 
mouse button (when the mouse pointer is 
on a scroll arrow or scroll bar) and the 
beginning of scroll-bar autorepeat activity. 


SV_SCROLLRATE Specifies the delay (in milliseconds) 
between scroll-bar autorepeat events. 

SV_NUMBEREDLISTS Reserved. 

SV_ERRORFREQ Specifies the frequency (in hertz) of a 

. WinAlarm function WA_ERROR sound. 

SV_NOTEFREQ Specifies the frequency (in hertz) of a 
WinAlarm function WA_NOTE sound. 

SV_WARNINGFREQ Specifies the frequency (in hertz) of a 
WinAlarm function WA_WARNING 
sound. 

SV_ERRORDURATION Specifies the duration (in milliseconds) of 
a WinAlarm function WA_ERROR 
sound. 

SV_NOTEDURATION Specifies the duration (in milliseconds) of 
a WinAlarm function WA_NOTE sound. 

SV_WARNINGDURATION Specifies the duration (in milliseconds) of 
a WinAlarm function WA_WARNING 
sound. 

SV_CXSCREEN Specifies the number of pels along the 
screen’s x-axis. 

SV_CYSCREEN Specifies the number of pels along the 
screen’s y-axis. 

SV_CXVSCROLL Specifies the number of pels along the 

x-axis of a vertical scroll bar. 

SV_CYHSCROLL Specifies the number of pels along the 
y-axis of a horizontal scroll bar. 

SV_CXHSCROLLARROW Specifies the number of pels along the 
x-axis of a horizontal scroll arrow. 

SV_CYVSCROLLARROW Specifies the number of pels along the 
y-axis of a vertical scroll arrow. 

SV_CXBORDER Specifies the number of pels along the 


x-axis of a window border. 
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‘Value 


SV_CYBORDER 


SV_CXDLGFRAME 


SV_CYDLGFRAME 


SV_CYTITLEBAR 


SV_CXHSLIDER 


SV_CYVSLIDER 


SV_CXMINMAXBUTTON 


SV_CYMINMAXBUTTON 


SV_CYMENU 


SV_CXFULLSCREEN 


SV_CYFULLSCREEN 


SV_CXICON 


SV_CYICON 


SV_CXPOINTER 


SV_CYPOINTER 


SV_DEBUG 


SV_CURSORLEVEL 


SV_POINTERLEVEL 


SV_TRACKRECTLEVEL 


SV_CTIMERS 
SV_CXBYTEALIGN 


Meaning 


Specifies the number of pels along the 
y-axis of a window border. 


Specifies the number of pels along the 
x-axis of a dialog-box frame. 


Specifies the number of pels along the 
y-axis of a dialog-box frame. 


Specifies the number of pels along the 
y-axis of a title-bar window. 


Specifies the number of pels along the 
x-axis of a horizontal scroll-bar slider. 


Specifies the number of pels along the 
y-axis of a vertical scroll-bar slider. 


Specifies the width (in pels) of a minimize 
or maximize button. 


Specifies the height (in pels) of a minimize 
or maximize button. 


Specifies the height (in pels) of a menu. 


Specifies the number of pels along the 
x-axis of the client window of a maximized 
frame window. 


Specifies the number of pels along the 
y-axis of the client window of a maximized 
frame window. 


Specifies the number of pels along an 
icon’s x-axis. 
Specifies the number of pels along an 
icon’s y-axis. 

Specifies the number of pels along the 
mouse pointer’s x-axis. 

Specifies the number of pels along the 
mouse pointer’s y-axis. 

Reserved. 

Specifies the cursor display count. The 


cursor is visible only when the display 
count is zero. 


Specifies the mouse-pointer display count. 
The mouse is visible only when the display 
count is zero. 


Specifies the tracking-rectangle display 
count. The tracking rectangle is visible 
only when the display count is zero. 


Specifies the number of available timers. 


Specifies a horizontal alignment that is 
more efficient for the device driver. 


Value 


SV_CYBYTEALIGN 


SV_EXTRAKEYBEEP 


SV_SETLIGHTS 


SV_INSERTMODE 


SV_MENUROLLDOWNDELAY 
SV_MENUROLLUPDELAY 
SV_ALTMNEMONIC 


SV_TASKLISTMOUSEACCESS 


SV_CSYSVALUES 
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Meaning 
Specifies a vertical alignment that is more 
efficient for the device driver. 


Specifies whether beep is turned on for 
extended keys (keys not on an IBM PS/2 
or compatible keyboard). 


Specifies if the system controls the key- 
board indicator lights. 


Specifies if insert mode is on or off for 
entry-field controls. 


Specifies the delay for menu roll down. 
Specifies the delay for menu roll up. 


Specifies if the Alt key is allowed as a 
mnemonic. 


Specifies if the Task List can be accessed 
by the right mouse button. 


Specifies the number of system values. 


See Also WinQuerySysValue 
Changes The following system values have been added: 
SV_EXTRAKEYBEEP 


SV_SETLIGHTS 
SV_INSERTMODE 


SV_MENUROLLDOWNDELAY 


SV_MENUROLLUPDELAY 
SV_ALTMNEMONIC 


SV_TASKLISTMOUSEACCESS 


@ WinSetWindowPos 


Correction 


BOOL WinSetWindowPos( hwnd, hwndinsertBehind, x, y, Cx, cy, fs) 


HWND hwnd; /« handle of window being set 
HWND hwndinsertBehind; /« placement-order handle 
SHORT x; /« horizontal position 
SHORT y; /« vertical position 

SHORT cx; /» width 

SHORT cy; /« height 

USHORT fs; /« window-positioning flags 


»/ 
»/ 
»/ 


The WinSetWindowPos function sets the position of a window. 


Parameters hwnd Identifies the window being set. 


hwndInsertBehind Identifies relative window-placement order. This parame- 
ter is ignored if the fs parameter is not set to SWP_ZORDER. If this parameter 
is HWND_BOTTOM, the hwnd window is placed behind all sibling windows. If 
it is HWND_TOP, the hwnd window is placed on top of all sibling windows. 
Other values identify the sibling window behind which the hwnd window is 


placed. 
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x Specifies the horizontal position of the hwnd window (in window coordinates 
relative to the lower-left corner of its parent window). This parameter is ignored 
if the fs parameter is not set to SWP_MOVE. 


y Specifies the vertical position of the hwnd window (in window coordinates 
relative to the lower-left corner of its parent window). This parameter is ignored 
if the fs parameter is not set to SWP_MOVE. 


cx Specifies the horizontal window size (in device units). This parameter is 
ignored if the fs parameter is not set to SWP_SIZE. 


cy Specifies the vertical window size (in device units). This parameter is 
ignored if the fs parameter is not set to SWP_SIZE. 


fs Identifies the window-positioning options. This parameter can be one or 
more of the following values: 


Value Meaning 


SWP_ACTIVATE The window is activated and the focus to 
be set to the window that lost the focus 
the last time the frame window was deac- 
tivated. The activated window may not 
become the top window if it owns other 
frame windows. 


SWP_DEACTIVATE Deactivates the window, if it is the active 
window. 
SWP_EXTSTATECHANGE This flag is for application use. It is used 


to pass an additional flag to the portion of 
code that is handling messages. 


SWP_FOCUSACTIVATE Specifies that a frame window is receiving 
the focus. This flag is set so that an 
application that is processing the 
WM_ADJUSTWINDOWPOS message can 
tell if the message was sent as the result of 
a focus change. 


SWP_FOCUSDEACTIVATE Specifies that a frame window is losing the 
focus. 

SWP_HIDE Specifies that the window is to be hidden 
when created. 

SWP_MAXIMIZE i With SWP_MINIMIZE, causes a window 


to be minimized, maximized, or restored. 
SWP_MAXIMIZE and SWP_MINIMIZE 
are mutually exclusive. If either 
SWP_MINIMIZE or SWP_MAXIMIZE is 
specified, then both SWP_MOVE and 
SWP_SIZE must also be specified. Win- 
SetWindowPos and WinSetMultWin- 
dowPos depend on the previous state of 
the window; these flags cause the appropri- 
ate state to be toggled, as follows: the x, 
y, cx, and cy parameters specify the size 
and position to which the window will be 
restored if it is subsequently restored. This 
should be the normal size of the window. 
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Value Meaning 

SWP_MINIMIZE See SWP_MAXIMIZE. 
SWP_MOVE Changes the window’s x,y position. 
SWP_NOADJUST Does not send a 


WM_ADJUSTWINDOWPOS message to 
the window while processing (the window 
cannot readjust itself). 


SWP_NOREDRAW Does not redraw changes. 
SWP_RESTORE Restores a minimized or maximized win- 
dow. 
SWP_SHOW Specifies that the window is to be shown 
when created. 
SWP_SIZE Changes the window size. 
SWP_ZORDER Changes the relative window placement. 
Return Value The return value is TRUE if the function is successful or FALSE if an error 
occurs. 
Comments If a window created with the CS_SAVEBITS style is moved, reduced in size, or 


hidden, the saved screen image is used to redraw the area uncovered when the 
window size changes, if those bits are still valid. 


If the CS_SIZEREDRAW style is present, the entire window area is assumed 
invalid if sized. Otherwise, a WM_CALCVALIDRECTS message is sent to the 
window to inform the window manager which bits it is possible to preserve. 


Messages sent from WinSetWindowPos and WinSetMultWindowPos have 
specific orders within the window positioning process. The process begins with 
redundancy checks and precaiculations on every window for each requested 
operation. For example, if SWP_SHOW is present but the window is already 
visible, then SWP_SHOW is turned off. If SWP_SIZE is present and the new 
size is equal to the previous size, SWP_SIZE is turned off. If the operations will 
create new results, the information is calculated and stored. For example, if 
being sized or moved, the new window rectangle is stored for later use. At this 
point, the WM_ADJUSTWINDOWPOS message is sent to any window that is 
being sized or moved. Also at this point, the WM_CALCVALIDRECTS mes- 
sage is sent to any window that is being sized and that does not have the 
CS_SIZEREDRAW window style. 


When the new window state is calculated, the window-management process 
begins. Window areas that can be preserved are moved from the old to the new 
positions, window areas that are invalidated by these operations are calculated 
and distributed as update regions, and so forth. When this is finished, and 
before any synchronous-paint windows are repainted, the WM_SIZE message is 
sent to any windows that have changed size. Next, all the synchronous-paint win- 
dows that can be repainted are repainted and the entire process is complete. 


If a synchronous-paint parent window has a size-sensitive area displayed that 
includes synchronous-paint child windows, the parent window will reposition 
those windows when it receives the WM_SIZE message. Their invalid regions 
will be added to the parent window’s invalid region, resulting in one update after 
the parent window’s WM_SIZE message, rather than many independent and sub- 
sequently duplicated updates. 
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Example 


See Also 


Corrections 


Certain windows are not positioned precisely to the parameters specified by this 
function. For example, frame windows without the FCF_NOBYTEALIGN style 
creation flag are not positioned to any specific screen coordinate. 
The following messages are sent by this function: 

Value Meaning 


WM_CALCVALIDRECTS Sent to determine the area of a window that 
it may be possible to preserve as the win- 
dow is sized. 


WM_SIZE Sent if the size of the window has changed, 
after the change has been effected. 
WM_MOVE Sent when a window with 


CS_MOVENOTIFY class style moves its 
absolute position. 


WM_ACTIVATE Sent if a different window becomes the 
active window. For more information, see 
the WinSetActiveWindow function. 


WM_ADJUSTWINDOWPOS Sent if SWP_NOADJUST is not specified. 
The message’s mpl parameter points to an 
SWP structure that has been filled in by the 
WinSetWindowPos function with the pro- 
posed move/size data. The window can 
adjust this new position by changing the 
contents of the SWP structure. 


This example gets the dimensions of the desktop window, and calls WinSet- 
WindowPos to place the application’s frame window in the upper left corner. By 
positioning the window relative to the desktop window, the window position is 
device-independent; it will work on any display adapter no matter what the verti- 
cal and horizontal resolution is. 


RECTL rel; 


WinQueryWindowRect (HWND_DESKTOP, G&rcl); 
WinSetWindowPos (hwndFrame, HWND_TOP, 


rceol.xLeft, /* x pos */ 
rcel.yTop - 60, /* y pos */ 
140, /* x size */ 


60, * y size */ 
SWP_ACTIVATE | SWP_MOVE | SWP_SIZE | SWP_SHOW); /* flags */ 


WinSetActiveWindow, WinSetMultWindowPos, WM_ADJUSTWINDOWPOS, 
WM_CALCVALIDRECTS 


Certain windows are not positioned precisely to the parameters specified by 
this function. For example, frame windows without a style creation flag of 
FCF_NOBYTEALIGN are not positioned to any specific screen coordinate. 


— WinSwitchToProgram New 
a ne ac cnn En 
USHORT WinSwitchToProgram( hSwitch) 


HSWITCH hSwitch; 


/« handle of application to activate »«/ 


The WinSwitchToProgram function makes an application the active application. 
The function succeeds only if the calling application is currently the active appli- 
cation (the application with the active window). 
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Parameters hSwitch Identifies the application to make active. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


PMERR_INVALID_SWITCH_HANDLE 
See Also WinInstStartApp 


WinTerminateApp New 
BOOL WinTerminateApp( happ) 


HAPP happ; 
The WinTerminateApp function terminates an application previously started 
with the WinInstStartApp function. 

Parameters happ Identifies the application to terminate. 


Return Value The return value is TRUE if the application is terminated successfully or NULL 
if an error occurs. 


Errors Use the WinGetLastError function to retrieve the error value, which may be one 
of the following: 


PMERR_INVALID_HAPP 
PMERR_CANNOT_STOP 


Comments The application to terminate must have been started using the WinInstStartApp 
function with the SAF_STARTCHILDAP?P option specified. 


If the specified application does not stop, this function returns TRUE. To 
ensure that the application has terminated, the application calling Win- 
TerminateApp must wait for the appropriate message to be posted to the win- 
dow specified in the WinInstStartApp function. 


See Also WinInstStartApp 
WinWindowFromID Correction 


HWND WinWindowFromI!D( hwnadParent, id) 
HWND hwndParent; /x parent-window handle »/ 
USHORT id; /« window identifier »/ 


The WinWindowFromID function returns the first child window that has the 
specified identifier of the specified parent window. 

Parameters hwndParent {dentifies the parent window. 
id Identifies the window. 


Return Value . The return value is a window handle. If no child window exists with identifier id 
the return value is NULL. 


Comments To obtain the window handle for an item within a dialog box, the hwndParent 
parameter is set to the dialog-box window’s handle and the id parameter is sct to 
the identifier of the item in the dialog template. 
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To obtain the window handle for a frame control, the hwndParent parameter is 
set to the frame window’s handle and the id parameter is set to one of the FID 
constants, indicating which frame control you want a handle of. 


The following list contains the frame control identifiers. Note that you must also 
define the INCL_.WINFRAMEMGR constant before including pmwin.h 


Value Meaning 

FID_CLIENT Identifies the client window. 
FID_HORZSCROLL Identifies the horizontal scroll bar. 
FID_MENU Identifies the application menu. 
FID_MINMAX Identifies the minimize/maximize box. 
FID_SYSMENU Identifies the system menu. 
FID_TITLEBAR Identifies the title bar. 


FID_VERTSCROLL Identifies the vertical scroll bar. 


Example This example calls WinWindowFromID to get the window handle of the system 
menu and calls WinSendMsg to send a message to disable the Close menu item. 

#define INCL_WINMESSAGEMGR /* includes message manager functions es 

ws 


#define INCL_WINFRAMEMGR /7* includes FID_ constants 
#include <os2.h> 


HWND hwndSysMenu; 
hwndSysMenu = WinWindowFromID(hwndDlg, FID_SYSMENU) ; 
WinSendMsg (hwndSysMenu, MM_SETITEMATTR, 


MPFROM2SHORT (SC_CLOSE, TRUE), 
MPFROM2SHORT (MIA_DISABLED, MIA_DISABLED)); 


See Also WinMultWindowFromIDs, WinWindowFromPoint 


Corrections The list of FID constants incorrectly identified FID_.MENU as referring to the 
system menu. It actually refers to the application menu. 


WinWindowFromPoint Change 
HWND WinWindowFromPoint( hwnd, pptl, fChildren, flock) 
HWND hwnd; /» handle of the window »/ 
~PPOINTL pptl; © /» address of structure with the point »/ 
BOOL fChildren; /»« scope flag »/ 
BOOL fLock; /» lock/unlock flag »/ 


The WinWindowFromPoint function finds the window that is below a specified 
point and that is a descendant of a specified window. This function checks only 
the descendants of the specified window. 


Parameters hwnd Identifies the window whose child windows are tested. 


pptl Points to a POINTL structure that contains the point to test, specified in 
window coordinates relative to the hwnd parameter. The POINTL structure has 
the following form: 


sa a struct _POINTL { 
LON x3 
LONG 

} POINTL; 


Return Value 


Parameters 
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fChildren Specifies which child windows to test. If [Children is TRUE, the 
function tests all the descendants of hwnd, including child windows of child win- 
dows. If fChildren is FALSE, the function tests only the immediate child win- 
dows of hwnd. 


fLock This parameter is ignored by MS OS/2 1.2 and later versions. 


If fChildren is FALSE, the return value is hwnd, a child of hwnd, or NULL. If 
fChildren is TRUE, the return value is the topmost window if that window is 
hwnd or a child of hwnd—unless another window of CS_HITTEST type is 
found, in which case the window returned may not be the topmost window. 


See Also WinWindowFromID 
Changes The fLock parameter is ignored by MS OS/2 1.2 and later versions. 
WinWriteProfileData Change 
BOOL WinWriteProfileData( hab, pszAppName, pszKeyName, pchBinaryData, cchData) 
HAB hab; /« handle of anchor block »/ 
_ PSZ pszAppName; /« address of application name «/ 
PSZ pszKeyName; /» address of keyname »/ 
PVOID pchBinaryData; /» address of data »/ 
USHORT cchData; /» length of data »/ 


The WinWriteProfileData function places binary data into the os2.ini file. The 
placement of the data is determined by an application name and a keyname that 
are passed to the function. The data can subsequently be retrieved by using the 
WinQueryProfileData function, specifying the same application name and key- 
name as are given in the pszAppName and pszKeyName parameters. 


hab Identifies the anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. If there is no 
application field in the os2.ini file that matches pszAppName, a new application 
field is created. 


pszKeyName Points to a null-terminated string that contains the keyname. 
The length of the string must be less than 1024 bytes, including the null terminat- 
ing character. If pszKeyName is NULL, all keynames and their data are deleted. 
The keyname is case-sensitive. If there is no keyname that matches pszKeyName, 
a new keyname field is created. If the keyname already exists, the existing value 
is overwritten. 


pchBinaryData Points to the binary data that is placed into the os2.ini file. 
There is no explicit termination character. If pchBinaryData is NULL, the previ- 
ous value associated with the pszKeyName parameter is deleted; otherwise, the 
data string becomes the value, even if it has a zero length. The amount of data 
should not exceed 64K. 


cchData Specifies the size (in bytes) of the pchBinaryData parameter. 
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Return Value 


The return value is TRUE if the function is successful, or FALSE if an error 
occurs. If the os2.ini file exists but is in cones form, WinWriteProfileData 
returns FALSE. 


Comments The WinWriteProfileData function provides compatibility with MS OS/2 1.1 and 
earlier versions. Applications intended exclusively for MS OS/2 1.2 and later 
versions should use the PrfWriteProfileData function. 

See Also PrfWriteProfileData, WinQueryProfileData 

Changes This function has been replaced by the PrfWriteProfileData function. 

WinWriteProfileString Change 

BOOL WinWriteProfileString( hab, pszAppName, pszKeyName, pszString) 

HAB hab; /x handle of anchor block »/ 

PSZ pszAppName; /x address of application name »/ 

PSZ pszKeyName; /« address of keyname »/ 

PSZ pszString; /« address of string to write »/ 


Parameters 


Return Value 


The WinWriteProfileString function places an ASCII string into the os2.ini file. 


_ The placement of the string is determined by an application name and a key- 


name that are passed to the function. The string can subsequently be retrieved 
by using the WinQueryProfileString function, specifying the same application 
name and keyname as are given in the pszAppName and pszKeyName parame- 
ters. 


hab Identifies the anchor block. 


pszAppName Points to a null-terminated string that contains the name of the 
application. The length of the string must be less than 1024 bytes, including the 
null terminating character. The application name is case-sensitive. If there is no 
application field in the os2.ini file that matches pszAppName, a new application 
field is created. 


pszKeyName Points to a null-terminated text string that contains the key- 
name. The length of the string must be less than 1024 bytes, including the null 
terminating character. If pszKeyName is NULL, all keynames and their data are 
deleted. The keyname is case-sensitive. If there is no keyname that matches 
pszKeyName, a new keyname field is created. If the keyname already exists, the 
existing value is overwritten. 


| pszString Points to a null-terminated ASCII string that is placed into the 


os2.ini file. If pszString is NULL, the previous value associated with pszKeyName 
is deleted; otherwise, the ASCII string becomes the value, even if it has a zero 
length. The size of the string should not exceed 64K. 


The return value is TRUE if the function is successful, or FALSE if an error 
occurs. Use the WinGetErrorInfo function to retrieve the error value, which 
may be one of the following: 


PMERR_CAN_NOT_CALL_SPOOLER 
PMERR_INVALID_PARM 
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Comments The WinWriteProfileString function provides compatibility with MS OS/2 1.1 
and earlier versions. Applications intended exclusively for MS OS/2 1.2 and 
later versions should use the PrfWriteProfileString function. 


See Also PrfWriteProfileString, WinQueryProfileString 
Changes This function has been replaced by the PrfWriteProfileString function. 
WM_ADJUSTWINDOWPOS . Change 
WM_ADJUSTWINDOWPOS 
pswp = (PSWP) PVOIDFROMMP (mp1); /* pointer to SWP structure */ 


The WM_ADJUSTWINDOWPOS message is sent when a window is about to be 
moved or sized. It gives the window an opportunity to adjust the new size and 
position before the window is actually moved and sized. 


Parameters pswp Low and high word of mp1. Points to an SWP structure that contains the 
new window size and position information. The SWP structure has the following 
form: 
typedef struct _SWP { 

USHORT fs; 
SHORT cy; 
SHORT cx; 
SHORT y; 
SHORT x; 


HWND hwndInsertBehind; 
HWND hwnd; 
} SWP; 


Return Value An application should return FALSE if it does not change the SWP structure. 
Otherwise, it should return on of the following values: 


Value Meaning 


AWP_MINIMIZED The window was minimized. 
AWP_MAXIMIZED The window was maximized. 
AWP_RESTORED The window was restored. 
AWP_ACTIVATE The window was activated. 
AWP_DEACTIVATE _ The window was deactivated. 


See Also WinCreateWindow, WM_CALCVALIDRECTS, 
WM_WINDOWPOSCHANGED 


Changes An application should return FALSE if it does not change the SWP structure. 
Otherwise, it should return on of the following values: 


Value Meaning 
AWP_MINIMIZED The window was minimized. 
AWP_MAXIMIZED The window was maximized. 
AWP_RESTORED The window was restored. 
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Value Meaning 


AWP_ACTIVATE The window was activated. 
AWP_DEACTIVATE ~The window was deactivated. 


—@ WM_APPTERMINATENOTIFY New 
WM_APPTERMINATENOTIFY . 
mp1 = MPFROMLONG((HAPP) happ) ; /* application handle * 
mp2 = MPFROMSHORT((USHORT) usRetCode) ; /* return code */ 


Parameters 


Return Value 


-The WM_APPTERMINATENOTIFY message is sent when a child application 


started by the WinInstStartApp function terminates. 


happ Low word of mp1. Identifies the application returned by the Win- 
InstStartApp function. 


usRetCode Low word of mp2. Specifies the return code from the application 
that has terminated. 


An application should return zero if it processes this message. 


See Also WinInstStartApp, WinTerminateApp 
™ WM_CALCFRAMERECT _ New 

WM_CALCFRAMERECT 
prcolFrame = (PRECTL) PVOIDFROMMP (mp1); /* pointer to RECTL structure */ 
fClient = (BOOL) SHORT1FROMMP (mp2) ; 7* client-indicator flag */ 
The WM_CALCFRAMERECT message is sent to a frame window when the 
WinCalcFrameRect function is called. The default window procedure calculates 
a client rectangle from a frame rectangle or calculates a frame rectangle from a 
client rectangle. 

Parameters prcl_ Low word of mp1. Points to the RECTL structure that contains the coor- 


dinates of the window. If the fClient parameter is TRUE, this structure contains 
the coordinates of the frame window, and on return, it contains the coordinates 
of a client window. If the fClient parameter is FALSE, this structure contains 
the coordinates of the client window, and on return, it contains the coordinates 
of a-frame window. 


The RECTL structure has the following form: 


typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


fClient Low word of mp2. Specifies whether the window to calculate is a client 
window or a frame window. If this value is TRUE, a client window is calculated. 
If this value is FALSE, a frame window is calculated. 


Return Value 
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If an application processes this message, it should return TRUE if successful or 
FALSE if an error occurs or the calculated rectangle is empty. 


See Also WinCalcFrameRect 
m@ WM_CALCVALIDRECTS Correction 

WM_CALCVALIDRECTS 
parclWindow = (PRECTL) PVOIDFROMMP (mp1) ; /* source rectangle */ 
pswpDest = (PSWP) PVOIDFROMMP (mp2) ; /* destination window */ 
The WM_CALCVALIDRECTS message is sent when a window is about to be 
resized. This allows the application to specify the coordinates of a rectangle that 
will be préserved and to designate where this rectangle will be moved in the 
resized window. Areas outside this rectangle will be redrawn. 

Parameters parclWindow Low and high word of mp1. Points to an array of two RECTL 


Return Value 


structures that contain the dimensions of the window before and after resizing. 
The first RECTL structure contains the source rectangle; the second RECTL 
structure contains the destination rectangle. The coordinates of the rectangles 
are relative to the parent window of the window. The RECTL structure has the 
following form: : 


typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


pswpDest Low and high word of mp2. Points to the SWP structure that con- 
tains information about the window after it is resized. The SWP structure has 
the following form: 


typedef struct _SWP { 


USHORT fs; 
SHORT cy; 
SHORT cx; 
SHORT y; 
SHORT x; 


HWND hwndInsertBehind; 
HWND hwnd; 
} SWP; 


If an application processes this message, it can return zero to indicate it has 
changed the rectangle itself, CVR_REDRAW if the entire window is to be 
redrawn, or a combination of the following values: 


Value Meaning 

CVR_ALIGNBOTTOM _ Align with the bottom edge of the window. 
CVR_ALIGNLEFT Align with the left edge of the window. 
CVR_ALIGNRIGHT Align with the right edge of the window. 
CVR_ALIGNTOP Align with the top edge of the window. 
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Comments The WM_CALCVALIDRECTS message is not sent if a window has the 
CS_SIZEREDRAW style because such windows are always completely redrawn 
when resized. 

See Also WM_ADJUSTWINDOWPOS 

Corrections The first parameter points to an array of two RECTL structures. The first struc- 
ture is the source rectangle; the second structure is the destination rectangle. 
The second parameter points to an SWP structure, not to a RECTL structure. 
The CVR_REDRAW was incorrectly spelled CV_REDRAW. 

™# WM_CHAR Change 
WM_CHAR 
fsKeyFlags = (USHORT) SHORT1EROMMP (mp1) ; /* key flags a/ 
uchRepeat = (UCHAR) CHAR3FROMMP (mp1) ; * repeat count a/ 
uchScanCode = (UCHAR) CHAR4FROMMP (mp1); /* scan code */ 
usChril = (UCHAR) CHAR1FROMMP (mp2); /* character */ 
usChr2 = (UCHAR) CHAR2FROMMP (mp2) ; /* 2nd byte of character */ 
usVKey = (USHORT) SHORT2FROMMP (mp2) ; /* virtual key a/ 
The WM_CHAR message is sent whenever the user presses a key. This message 
is placed in the queue associated with the window that has the focus. 

Parameters fsKeyFlags Low word of mp1. Specifies the keyboard control codes. It can be 


one or more of the following values: 


Value Meaning 

KC_CHAR The usChr parameter value is valid; otherwise, mp2 
contains zero. 

KC_SCANCODE The uchScanCode parameter value is valid; otherwise, 


uchScanCode contains zero. 


KC_VIRTUALKEY The usVKey parameter value is valid; otherwise, 
usVKey contains zero. 


KC_KEYUP The event was a key-up transition; otherwise, it was a 
key-down transition. 

KC_PREVDOWN The key was previously down; otherwise, it was previ- 
ously up. 

KC_DEADKEY The character code is a dead key. The application 


must display the glyph for the dead key without 
advancing the cursor. 


KC_COMPOSITE The character code was formed by combining the 
current key with the previous dead key. 


KC_INVALIDCOMP _ The character code was not a valid combination with 
the preceding dead key. The application must advance 
the cursor past the dead-key glyph and then, if the 
current character is not a space, it must beep the 
speaker and display the new character code. 


KC_LONEKEY This bit is set if the key was pressed and released 
: without any other keys being pressed or released 
between the time the key was pressed and released. 


Comments 


- Example 


Return Value 


See Also 
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Value Meaning 

KC_SHIFT The shift state was active when the key is pressed or 
released. 

KC_ALT The ALT state was active when the key was pressed or 
released. 

KC_CTRL The CONTROL state was active when the key was 


pressed or released. 


uchRepeat Low byte of high word of mp1. Specifies the repeat count of the 
key. 
uchScanCode High byte of high word of mp1. Specifies the character scan 


code of the character. usChr1 First byte of the low word of mp2. Specifies the 
ASCII character. 


usChr2 Second byte of the low word of mp2, for double-byte characters only. 
Specifies second byte of the character, or is zero for standard ASCII. 


usVKey High word of mp2. Specifies the virtual-key code. 


Generally, all WM_CHAR messages generated from actual user input have the 

KC_SCANCODE code set. However, if the message has been generated by an 

application that has issued the WinSetHook function to filter keystrokes, or if it 
was posted to the application queue, this code may not be set. 


The CHARMSG macro can be used to access the WM_CHAR message parame- 
ters. This macro defines a CHARMSG structure pointer that has the following 
form: 


struct _CHARMSG { 


USHORT chr; /* mp2 */ 
USHORT vkey; 
USHORT fs; /* mpl */ 


UCHAR cRepeat; 
UCHAR scancode; 
}; 


When the character returned is a double-byte character, then the second byte of 
mp2 contains the second byte of the character. For standard ASCII, the second 
byte is zero. 


This example uses the CHARMSG macro to process a WM_CHAR message. It 
first uses the macro to determine if a key was released. It then uses the macro to 
generate a switch statement based on the character received. 


MRESULT CALLBACK GenericWndProc(hwnd, usMessage, mpl, mp2) 
HWND hwnd; 

USHORT usMessage; 

MPARAM mp1; 

MPARAM mp2; 

{ 


switch (usMessage) { 
case WM_CHAR: 
if (CHARMSG(&usMessage)->fs & KC_KEYUP) { 
switch (CHARMSG(&usMessage)->chr) { 


An application should return TRUE if it processes the message; otherwise it 
should return FALSE. 


WinSetHook, WM_NULL, WM_TRANSLATEACCEL, WM_VIOCHAR 
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Changes 


For double-byte character sets, the second parameter (mp2) of WM_CHAR con- 
tains both bytes of the double-byte character. 


Change 


WM_CLOSE 


Parameters 
Return Value 


Comments 


Example 


See Also 


Changes 


WM_CLOSE 


The WM_CLOSE message is sent as a signal that the window or its application 
should terminate. This message allows the window to control the termination 
process. ; 


This message does not use any parameters. 
An application should return zero if it processes this message. 


If WM_CLOSE is passed to the WinDefDlgProc function, the function calls the 
WinDismissDlg function and passes the DID_CANCEL result code to it. 


In the following example, the fChanges variable is checked. If it is TRUE, the 
user is asked if he or she wants to exit without saving any changes. If the user 
responds by choosing the No button, then zero is returned and the application 
does not exit. If the user responds by choosing the Yes button, then a 
WML_OQUIT message is posted so that the application will terminate. 
case WM_CLOSE: 
if (fChanges) { 
if (WinMessageBox (HWND_DESKTOP, hwndClient, 
"Do you want to exit without saving your changes?", 


"| 0, MB_NOICON | MB_YESNO) == MBID_NO) 
return (OL); 


} 
WinPostMsg(hwnd, WM_QUIT, OL, OL); 
return (OL); 


WinDefWindowProc, WinMessageBox, WinPostMsg, WM_QUIT 


If a dialog window has a system menu, selecting the “Close” menu item calls the 
WinDismissDlg function, passing the DID_CANCEL result code. Previous ver- 
sions of MS OS/2 closed the application, rather than only the dialog box. 


WM_DRAWITEM . Correction. 


Parameters 


WM_DRAWITEM 
id = (USHORT) SHORT1FROMMP (mp1) ; /* window ID */ 
poi = (POWNERITEM) PVOIDFROMMP (mp2) ; /* pointer to OWNERITEM */ 


The WM_DRAWITEM message is sent to the owner of a list box when an item 
in an owner-drawn list needs to be drawn or highlighted. The list box must have 
the LS_LOWNERDRAW style. The WM_DRAWITEM message is also sent to 
the owner of a menu when an item in the owner-drawn menu needs to be drawn 
or highlighted. The menu must have the MIS_OWNERDRAW style. 


id Low word of mp1. Identifies the window of the list-box or menu control | 
sending this message. 


poi Low and high word of mp2. Points to an OWNERITEM structure. The 
OWNERITEM structure has the following form: 
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typedef struct _OWNERITEM { 
HWND hwnd; 
HPS hps; 
USHORT fsState; 
USHORT fsAttribute; 
USHORT fsStateOld; 
USHORT fsAttributeOld; 
RECTL relitem; 
SHORT idItem; 
ULONG hItem; 

} OWNERITEM; 


Return Value The application should return TRUE if it draws the list-box item; it should 
return FALSE if the list box should draw the item. If the WM_DRAWITEM 
message is sent to a menu, the return value is ignored. 


Comments When an item is to be drawn, the fsState field and the fsStateOld field of the 
OWNERITEM structure will be equal. The application should draw the item and 
return TRUE, or it should return FALSE to let the list box draw the item. The 
list box can draw only text items, so the application must handle the drawing of 
other types of objects. 


When an item is to be highlighted, the fsState field is TRUE and the fsStateOld 
field is FALSE. In this case, the application should carry out the highlighting 
and set fsState and fsStateOld equal to FALSE before returning TRUE, or it 
should return FALSE so the list box can perform default highlighting of the 
item. 


When highlighting is to be removed from an item, the fsState field is FALSE 
and the fsStateOld field is TRUE. An application can remove the highlighting, 
set the fsState and fsStateOld equal to FALSE and return TRUE, or it can 
return FALSE to let the list box remove the highlighting. 


See Also LM_QUERYITEMTEXT 


Corrections The application should return TRUE if it draws the list-box item; it should 
return FALSE if the list box should draw the item. If the WM_DRAWITEM 
message is sent to a menu, the return value is ignored. 


@ WM_FORMATFRAME Correction 
WM_FORMATERAME 
paswp = (paswp) PVOIDFROMMP (mp1) ; /* pointer to SWP array Wf 
prcol = (PRECTL) PVOIDFROMMP (mp2) ; /* pointer to RECTL structure */ 


The WM_FORMATFRAME message is sent to a frame window to calculate the 
sizes and positions of the frame controls and the client window. The frame- 
window procedure sends the message to its client window and, if the client win- 
dow returns TRUE (indicating that it processed the message), no further action 
occurs. Otherwise, the frame window calls the WinFormatFrame function. 


Parameters paswp Low and high word of mp1. Points to an array of SWP structures. The 
array elements are filled in the order of the FID values of the frame controls, 
with the FID_CLIENT window always the last element in the array. The SWP 
structure has the following form: . 
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Return Value 


typedef struct _SWP { 


USHORT fs; 
SHORT cy; 
SHORT cx; 
SHORT y; 
SHORT x; 


HWND hwndInsertBehind; 
HWND hwnd; 
} SWP; 


prel_ Low and high word of mp2. Points to a RECTL structure that contains 
the rectangle within which the frame controls are formatted. The RECTL struc- 
ture has the following form: 


typedef struct _RECTL { 
LONG xLeft; 
LONG yBottom; 
LONG xRight; 
LONG yTop; 
} RECTL; 


An application should return TRUE if it processes this message. 


Comments Note that the paswp parameter points to memory allocated according to the 
value returned by the WM_QUERYFRAMECTLCOUNT message. The applica- 
tion must not write beyond this area. 

See Also WinFormatFrame | 

Corrections The parameters were reversed. The first parameter is the array of SWP struc- 
tures; the second parameter is a pointer to a RECTL structure. 

WM_MEASUREITEM Change 
WM_MEASUREITEM ; 

id = SHORTIFROMMP (mp1) ; /* list-box identifier */ 

poi = (POWNERITEM) PVOIDFROMMP(mp2);  /* pointer to OWNERITEM */ 

The WM_MEASUREITEM message is sent to calculate the height of each item 
in a window. It is normally sent to list boxes and menus. All items are the same 
height in a list box or menu. 

Parameters id Low word of mp1. Specifies the window. 


poi Low and high word of mp2. When this message is sent to a menu window, 
this parameter points to an OWNERITEM structure. Otherwise, this parameter 
is not used. The OWNERITEM structure has the following form: 


typedef struct _OWNERITEM { 
HWND hwnd; 
HPS hps; 
USHORT  fsState; 
USHORT fsAttribute; 
USHORT fsStateOld; 
USHORT fsAttributeOld; 
RECTL relItem; 
SHORT idItem; 
ULONG hitem; 

} OWNERITEM; 


Return Value 


See Also 


Changes | 


WM_MOVE 


Parameters 
Return Value 
See Also 


Corrections 
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If this message is processed by a list box, the low word of the return value con- 
tains the height of the list-box item. If the style LS_HORZSCROLL is set, the 
high word contains the length of the list-box item; otherwise, the high word must 
be set to zero. 


If this message is processed by a menu, the return value is ignored. The width 
and height are returned by placing their dimensions in the OWNERITEM struc- 
ture passed in the poi parameter. 


LM_SETITEMHEIGHT 


If the style LS_LHORZSCROLL is set, WM_MEASUREITEM must return the 
length of the list-box item as the high word of the return value. 


Correction 


WM_MOVE 


The WM_MOVE message is sent when a window with CS_MOVENOTIFY style 
changes its absolute position or when a parent window of that window is moved. 
The window’s new position can be obtained by calling the WinQueryWindowPos 
function. 


This message does not use any parameters. 
An application should return zero if it processes this message. 
WinQueryWindowPos 


Use the WinQueryWindowPos function, not the WinQueryWindowRect function 
to obtain the window’s position. 


WM_PRESPARAMCHANGED New 


Parameters 


WM_PRESPARAMCHANGED 


idParam = (ULONG) LONGEROMMP (mp1) ; /* presentation-parameter ID */ 


The WM_PRESPARAMCHANGED message is sent when a presentation 
parameter has changed. 


idParam Low and high word of mp1. Identifies the presentation parameter 
that changed. This parameter can be one of the following values: 


Value Meaning 
PP_FOREGROUNDCOLOR RGB foreground color 
PP_FOREGROUNDCOLORINDEX Color index of fore- 


ground color 
PP_BACKGROUNDCOLOR RGB background color 
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See Also 


Value 


PP_BACKGROUNDCOLORINDEX 


PP_HILITEFOREGROUNDCOLOR 


PP_HILITEFOREGROUNDCOLORINDEX 


PP_HILITEBACKGROUNDCOLOR 


PP_HILITEBACKGROUNDCOLORINDEX 


PP_DISABLEDFOREGROUNDCOLOR 


PP_DISABLEDFOREGROUNDCOLORINDEX 


PP_DISABLEDBACKGROUNDCOLOR 


PP_DISABLEDBACKGROUNDCOLORINDEX 


PP_BORDERCOLOR 
PP_BORDERCOLORINDEX 


PP_FONTNAMESIZE 
PP_FONTHANDLE 


WinQueryPresParam, WinSetPresParam 


mM WM_QUERYHELPINFO| 


Parameters 
Return Value 


See Also 


WM_QUERYHELPINEO 


The WM_QUERYHELPINFO message is sent to a frame window to retrieve the 


handle of the help instance. 


This message does not use any parameters. 


Meaning 


Color index of back- 
ground color 


RGB color of foreground 
highlighted area 


Color index of fore- 
ground highlighted area 
RGB color of back- 
ground highlighted area. 
Color index of back- 
ground highlighted area 


RGB foreground disabled 
color 


Color index of fore- 
ground disabled color 


RGB color of back- 
ground disabled color 


Color index of back- 
ground disabled color 


RGB color of window 
border 


Color index of window 
border 


Font size 
Font handle 


New 


An application should return the help instance handle associated with the win- 
dow. If no handle is available, the application should return NULL. 


WM_SETHELPINFO 
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mM WM_SAVEAPPLICATION New 
WM_SAVEAPPLICATION 
mpl = OL; /* not used, must be zero */ 
mp2 = OL; /* not used, must be zero */ 


Return Value 


See Also 


The WM_SAVEAPPLICATION message notifies an application to save its 
current state (for example, due to a pending system shutdown). 


Parameters This message does not use any parameters. 

Comments When a system shutdown is requested, MS OS/2 enumerates the applications in 
the Task List and sends each application a WM_SAVEAPPLICATION mes- 
sage. The sender of the WM_SAVEAPPLICATION message suspends execu- 
tion until it receives a reply. The receiving application must not display dialog or 
message boxes. Doing so could delay the reply and result in unacceptable delays 
in completing the shutdown. 

In MS OS/2, version 1.2, the application must save its state to the os2.ini file by 
using the WinWriteProfileString or WinWriteProfileData function, or it must 
save its state to some other file. 
To be compatible with future releases of MS OS/2, an application should call 
WinDefWindowProc after processing the WM_SAVEAPPLICATION message. 
Each application should maintain only one “saved state.” If an application 
receives multiple WM_SAVEAPPLICATION messages, it should over- 
write the previous “saved state” with a new “saved state” for each new 
WM_SAVEAPPLICATION message. 
See Also WinDefWindowProc, WinWriteProfileData, WinWriteProfileString 

m@ WM_SETHELPINFO New 
WM_SETHELPINFO 
hwnd = HWNDFROMMP (mp1) ; /* handle of help table */ 
The WM_SETHELPINFO message is sent to a frame window to set the handle 
of the help instance for that window. 

Parameters hwnd Low and high word of mp1. Identifies the help instance. 


An application should return zero if it processes this message. 


WM_QUERYHELPINFO 
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M WM_WINDOWPOSCHANGED New 
WM_WINDOWPOSCHANGED 
mp1 = MPFROMP (<paswp>) ; /* pointer to array of SWP structures */ 
mp2 = MPFROMLONG(<flReturn>) ; 7* return-value flag */ 


Parameters 


Comments 


Example 


See Also 


The WM_WINDOWPOSCHANGED message is sent whenever the size of a 
window changes. 


paswp Low and high word of mp/J. Points to an array of two SWP structures: 
the first SWP structure contains the new state of the window; the second SWP 
structure contains the previous state of the window. The SWP structure has the 
following form: 


typedef struct _SWP { 
USHORT fs; 


SHORT cy; 
SHORT cx; 
SHORT y; 
SHORT x; 


HWND hwndInsertBehind; 
HWND hwnd; 
} SWP; 


flReturn Specifies the return value of the WM_ADJUSTWINDOWPOS mes- 
sage; it is FALSE if SWP_NOADJUST was specified. 


The entire window state is filled in both SWP structures; however, the fs field of 
the first SWP structure contains only those bits that correspond to the actual 
changes that occurred. For example, if a window is resized, fields x and y con- 
tain the position of the window even though it did not move, but the fs field 
does not contain the SWP_MOVE flag. 


This example processes the WM_WINDOWPOSCHANGED message and 
assigns the two structures to pointers: 

PSWP pswpNew, pswpOld; 

case WM_WINDOWPOSCHANGED: 


pswpNew = PVOIDEROMMP (mp1) ; 
pswpOld = pswpNew + 1; 


WinCreate Window, WM_ADJUSTWINDOWPOS, WM_CALCVALIDRECTS 
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4.1 Introduction 


This chapter describes the new and updated types, macros, and structures used 
with MS OS/2, version 1.2, functions and messages. For a complete list of all 
MS OS/2 types, macros, and structures, see the Microsoft Operating System/2 
Programmer’s Reference, Volume 2 and Volume 3. 


The MS OS/2 functions use many types, macros, and structures that are not part 
of the standard C language. These types, macros, and structures have been 
defined to make the task of creating MS OS/2 programs easier and to make pro- 
grams sources clearer and easier to understand. 


All types, macros, and structures in this manual are defined in the MS OS/2 
C-language include files. You may also want to use these when developing MS 
OS/2 programs in other computer languages, such as Pascal or assembly 
language. If include files for a given language are not available, you can translate 
the definitions given in this chapter by following these guidelines: 


m Numbers must be integers or fixed-point real numbers. MS OS/2 func- 
tions do not support floating-point numbers. An MS OS/2 program can 
use floating-point numbers as long as an appropriate run-time library or 
coprocessor is supplied and floating-point numbers are not used as 
parameters to the MS OS/2 functions. 


m Structures must be packed. Some compilers align each new field in a 
structure on word or double-word boundaries. This may leave unused 
bytes in a structure if a given field is smaller than the width between 
boundaries. MS OS/2 functions require that unused bytes be removed 
from structures. 


™ Reserved fields in structures should be set to zero. Unless otherwise 
specified, MS OS/2 functions expect reserved fields to be set to zero to 
avoid compatibility problems with future releases of MS OS/2. 


™@ Variable-length structures must be supported. Several MS OS/2 func- 
tions use variable-length structures to receive and/or return information. 
In a variable-length structure, the number of fields in the structure varies 
depending on when the structure is used. In the C language, programs 
typically support variable-length structures by allocating enough memory 
for the current number of fields and accessing those fields by using a 
pointer to the structure. Programs in other languages may use this 
method or devise their own method for supporting variable-length struc- 
tures. 


m All 16-bit sated must be relative to an explicitly defined segment regis- 
ter. Some compilers assume that the ds and ss registers contain the 
same value and implicitly use one segment for both. MS OS/2 does not 
guarantee that the ds and ss registers will be equal. This is especially 
true in dynamic-link libraries and programs that use callback functions 
(for example, window procedures). 


# All 32-bit pointers must consist of a selector:offset pair. MS OS/2 func- 
tions do not use physical addresses (that is, an address that represents a 
32-bit offset from the beginning of physical memory). (One exception to 
this rule is the VioGetPhysBuf function, which requires a physical 
address to video memory.) 
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4.2 Types 


The following data types are new or modified for MS OS/2, version 1.2: 


Type Meaning 

HAPP 32-bit value used as an application handle. 

HINI 32-bit value used as an initialization-file handle. 

HLIB 16-bit value used as a module handle. 

HPROC 32-bit value used as a pointer to a procedure (function). 
LINE 32-bit value used as a line number. 

PHINI 32-bit value used as a pointer to an initialization-file handle. 


4.3 Macros 


There are no new or updated macros for MS OS/2, version 1.2. 


4.4 Structures 


The following structures are used by the MS OS/2, version 1.2, functions 
described in this manual. 


mM AVAILDATA 
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New 


typedef struct _AVAILDATA { /* avidt */ 
USHORT cbpipe; 
USHORT cbmessage; 

} AVAILDATA; 


The AVAILDATA structure contains information about the bytes in a named 
pipe. 


Fields cbpipe Specifies the number of bytes left in the pipe. 
cbmessage Spccifies the number of bytes left in the current message. 
See Also DosPeekNmPipe 
@ CHARBUNDLE Change 
typedef struct _CHARBUNDLE { /* cbhnd */ 
LONG 1Color; 
- LONG 1BackColor; 


Fields 


USHORT usMixMode; 
USHORT usBackMixMode; 
USHORT usSet; 
USHORT usPrecision; 
SIZEEF sizfxCell; 
POINTL ptilAngle; 
POINTL ptiShear; 
USHORT usDirection; 

} CHARBUNDLE; 


The CHARBUNDLE structure contains fields that describe the current character 
attributes in the application’s presentation space. MS OS/2 uses these attributes 
whenever the application draws text using one of the Gpi functions. 


IColor Specifies the character foreground color. 
IBackColor Specifies the character background color. 


usMixMode Specifies the foreground mix mode. MS OS/2 uses this mix 
mode when it combines the character foreground color and the current drawing- 
surface color. 


usBackMixMode _ Specifies the background mix mode. MS OS/2 uses this 
mix mode when it combines the character background color and the current 
drawing-surface color. 


usSet Specifies the character set. This value is the local identifier for the 
current logical font. It can be any value from 1 through 254. 


usPrecision Specifies the current character mode. There are three possible 
modes: mode 1, mode 2, and mode 3. If mode 1 is set and the current font is an 
image font, MS OS/2 ignores the current shear, angle, and box attributes. If 
mode 2 is set and the current font is an image font, MS OS/2 uses the current 
shear, angle, and box attributes. If mode 3 is set and the current font is an 
image font, MS OS/2 issues an error message. If the current font is a vector 
font, MS OS/2 always uses the current shear, angle, and box attributes (regard- 
less of the mode). 
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sizfxCell Specifies the character-cell size (in world units). This SIZEF struc- 
ture contains two fixed values. 


ptlAngle Points to the POINTL structure that contains the coordinates of the 
endpoint of the character-angle vector. The baseline of vector characters is 
drawn parallel to the character-angle vector. 


ptlShear Points to the POINTL structure that contains the coordinates of the 
endpoint of the character-shear vector. The vertical strokes in vector characters 
are drawn parallel to the character-shear vector. 


usDirection Specifies the character direction. The default direction is from 
left to right. This parameter can be one of the following values: 


Value Meaning 
CHDIRN_LEFTRIGHT Left to right 
CHDIRN_RIGHTLEFT Right to left 
CHDIRN_TOPBOTTOM Top to bottom 
CHDIRN_BOTTOMTOP Bottom to top 
See Also GpiQueryAttrs, GpiQueryCharAngle, GpiQueryCharBox, GpiQueryCharSet, 
GpiQueryCp, GpiSetAttrs, GpiSetCharAngle, GpiSetCharBox, GpiSetCharSet, 
GpiSetCp, POINTL, SIZEF 
Changes The following character directions can now be specified for the usDirection 
field: 
Value Meaning 
CHDIRN_LEFTRIGHT Left to right 
CHDIRN_RIGHTLEFT ; Right to left 
CHDIRN_TOPBOTTOM Top to bottom 
CHDIRN_BOTTOMTOP _ Bottom to top 
mM DENA1 New 
typedef struct _DENA1 { /* dena */ 
UCHAR reserved; 
UCHAR cbName; 
USHORT cbValue; 
UCHAR szName[1]; 
} DENA1; 
The DENALI structure contains the names of the extended attributes returned by 
the DosEnumAttribute function. 
Fields reserved Specifies a reserved value; must be zero. 


See Also 


cbName _ Specifies the length of the extended-attribute name. 
cbValue Specifies the length of the extended-attribute value. 
szName[1] Contains the name of the extended attribute. 


DosEnumAttribute 
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m@ EAOP New 
typedef struct _EAOP { /* eaop */ 
PGEALIST fpGEAList; 
PFEALIST fpFEAList; 
ULONG oError; 
} EAOP; 
The EAOP structure contains extended-attribute information needed by the file- 
system function calls. 
Fields fpGEAList Points to the GEALIST structure that lists the extended attributes 
to retrieve. 
fpFEAList Points to the FEALIST structure that lists the extended attributes 
found. 
oError Specifies the offset, from the beginning of the structure, at which an 
error occurred. 
See Also DosFindFirst2, DosMkDir2, DosOpen2, DosQFileInfo, DosQPathInfo, DosSet- 
FileInfo, DosSetPathInfo, FEALIST, GEALIST 
M@ ENTRYFDATA New 
typedef struct _ENTRYFDATA { /* efd */ 
USHORT cb; 
USHORT cchEditLimit; 
USHORT ichMinSel; 
USHORT ichMaxSel; 
} ENTRYFDATA; 
The ENTRYFDATA structure contains control data used to specify the charac- 
teristics of an entry-field control. 
Fields cb Specifies the size of the structure (in bytes). Programs written in the C 


language should use the sizeof operator to set this field. 


cchEditLimit Specifies the maximum number of characters than can be 
entered in the edit control. 


ichMinSel Specifies the beginning point of the current selection within the 
entry field’s text buffer. 


ichMaxSel Specifies the end point of the current selection within the entry 
field’s text buffer. 
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mM FATTRS Change 
typedef struct _FATTRS { /* fat */ 
USHORT usRecordLength; 
USHORT fsSelection; 
LONG 1Match; 
CHAR szFacename [FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG lMaxBaselineExt; 
LONG lAveCharWidth; 
USHORT fsType; 
USHORT fsFontUse; 
} FATTRS; 
The FATTRS structure specifies the attributes of the logical font to be created by 
the VioCreateLogFont or GpiCreateLogFont function. 
Fields usRecordLength Specifies the length of the structure. 


fsSelection Specifies one or more character attributes. This field can be any 
combination of the following values: 


Value Meaning 

FATTR_SEL_ITALIC Specifies italic characters. 
FATTR_SEL_OUTLINE Specifies an outline font. 
FATTR_SEL_STRIKEOUT Specifies strikeout characters. 
FATTR_SEL_UNDERSCORE Specifies underscored characters. 
FATTR_SEL_BOLD Specifies bold characters. 


IMatch Specifies the match number for a specific font. The VioQueryFonts 
and GpiQueryFonts functions return a unique match number for each font. 
When this number is specified in the IMatch field, the specified font is used. If 
the IMatch field is zero, the system determines which font gives the best map- 
ping to the required attributes. 


szFacename[FACESIZE] | Spccifies the typeface name of the font. 
idRegistry Specifics the registry number of the font. 
usCodePage Specifies the code-page identifier of the font. 


IMaxBaselineExt Specifies the sum of the maximum ascender and descender 
values for a font. 


IAveCharWidth Specifies the average width of a character in a font. This 
value is obtained by multiplying the width of each lowercase letter by a weighted 
factor, adding the results for all of the letters in the alphabet, and dividing by 
1000. The factor corresponds to the frequency of use for a particular letter. For 
example, the letter e appears frequently in text while the letter q does not; there- 
fore, the factor assigned to e would be greater than the factor assigned to q. 
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fsType Specifies the type of the font. This field can include one or more of 
the following values: 


Value Meaning 

FATTR_TYPE_KERNING Specifies a kerned font. 
FATTR_TYPE_MBCS Specifies a multiple-byte character-set font. 
FATTR_TYPE_DBCS Specifies a double-byte character-set font. 


FATTR_TYPE_ANTIALIASED Specifies an anti-aliased font. 


fsFontUse Specifies how the font is related to the character attributes. This 
field can be any combination of the following values: 


Value Meaning 

FATTR_FONTUSE_NOMIX The application cannot mix text 
and graphics. 

FATTR_FONTUSE_OUTLINE Requests an outline font. 


FATTR_FONTUSE_TRANSFORMABLE = Requests a transformable font. 


See Also GpiCreateLogFont, GpiQueryFonts, VioCreateLogFont, VioQueryFonts 
Changes FATTR_TYPE_FIXED can no longer be specified for the fsType field. The fol- 
lowing new constants can be specified for fsType: 
Value Meaning 
FATTR_TYPE_MBCS Specifies a multiple-byte character-set font. 
FATTR_TYPE_DBCS Specifies a double-byte character-set font. 
FATTR_TYPE_ANTIALIASED _ Specifies an anti-aliased font. 
FATTR_SEL_OUTLINE can be specified for the fsSelection field. 
Corrections The FATTR_SEL_HOLLOW constant did not exist in the include files. A new 
constant, FATTR_SEL_OUTLINE, gives you hollow (outlined) characters. 
FEA New 
typedef struct _FEA { /* fea */ 
BYTE fEA; 
BYTE cbName; 
USHORT cbValue; 
} FEA; 
The FEA structure contains the values of extended attributes. 
Fields fEA Specifies one or more flags. In MS OS/2, version 1.2, the only flag avail- 


able is FEA_NEEDEA, indicating an extended-attribute bit is needed. 


cbName Specifies the length of the extended-attribute name, not including the 
null terminating character. 


cbValue Specifies the length of the extended-attribute value. 
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Comments This structure also contains a variable-length portion immediately following the 
cbValue field. This variable-length portion contains the extended-attribute name 
and the extended-attribute value. 

See Also EAOP, FEALIST, GEA, GEALIST 

FEALIST New 
typedef struct _FEALIST { /* feal */ 

ULONG cbList; 
FEA list{1]; 
} FEALIST; 
The FEALIST structure contains one or more extended attributes. 

Fields cbList Specifies the size (in bytes) of the structure. 
list{1] | Contains an array of one or more FEA structures. 

Comments The FEALIST structure contains a list of the extended attributes that were 
found. The GEALIST structure contains names of extended attributes to retrieve 
information for. 

See Also DosFindFirst2, DosMkDir2, DosOpen2, DosQPathInfo, DosSetFileInfo, 
DosSetPathInfo, EAOP, FEA, GEALIST 

FILEFINDBUF2 New 
typedef struct _FILEFINDBUF2 { /* findbuf2 */ 

EFDATE fdateCreation; 

ETIME ftimeCreation; 

EDATE fdateLastAccess; 

ETIME ftimeLastAccess; 

EDATE fdateLastWrite; 

ETIME ftimeLastWrite; 

ULONG cbhFile; 

ULONG cbFileAlloc; 

USHORT attrFile; 

ULONG cbList; 

UCHAR cchName; 

CHAR achName [CCHMAXPATHCOMP] ; 
} FILEFINDBUF2; 
The FILEFINDBUE2 structure contains information about a file. 

Fields fdateCreation Specifies the date the file was created. 


ftimeCreation Specifies the time the file was created. 

fdateLastAccess Specifies the date the file was last accessed. 
ftimeLastAccess Specifies the time the file was last accessed. 
fdateLastWrite Specifies the date the file was last written to. 
ftimeLastWrite Specifies the time the file was last written to. 


See Also 


m FILESTATUS2 


Fields 


Comments 


See Also 
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cbFile Specifies the end of file data. 
cbFileAlloc Specifies the allocated file size. 
attrFile Specifies the file attributes. 


cbList Specifies the size (in bytes) of the buffer needed for the list of 
extended attributes in a FIL.IQUERYEASFROMLIST level request (see Dos- 
FindFirst2). 


cchName Specifies the length of the null-terminated filename. 
achName[CCHMAXPATHCOMP] _ Specifies the null-terminated filename. 


DosFindFirst2, DosFindNext2, FDATE, FTIME 


New 


typedef struct _FILESTATUS2 { /* fsts2 */ 
FDATE fdateCreation; 
FTIME ftimeCreation; 
FDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
ETIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 
ULONG cbList; 

} FILESTATUS2; 


The FILESTATUS2 structure contains information about the status of a file. 


fdateCreation Specifies the date the file was created. 
ftimeCreation Specifies the time the file was created. 
fdateLastAccess Specifies the date the file was last accessed. 
ftimeLastAccess Specifies the time the file was last accessed. 
fdateLastWrite Specifies the date the file was last written to. 
ftimeLastWrite Specifies the time the file was last written to. 
cbFile Specifies the end of file data. 

cbFileAlloc Specifies the allocated file size. 

attrFile Specifies the file attributes. 

cbList Specifies the size of the extended-attribute buffer. 


The cbFile, cb ileAlloc, and attrFile fields are not used by the DosSetFileInfo 
function. 


DosQFileInfo, DosQPathInfo, DosSetFileInfo 
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HE FIOLOCKCMD 


Fields 


See Also 


i FIOLOCKREC 


Fields 


See Also 


New 


typedef struct _FIOLOCKCMD { /* fle */ 
USHORT usCmd; 
USHORT cLockCnt; 
ULONG cTimeOut; 

} FIOLOCKCMD; 


The FIOLOCKCMD structure contains information used by the DosFileIO func- 
tion for locking a file. 


usCmd _ Specifies the command to pass to the DosFileIO function. This field 
should be set to FIO_LOCK. 


cLockCnt Specifies the number of FIOLOCKREC structures that follow this 
structure. An FIOLOCKREC structure specifies the area of the file to lock and 
whether another process can read the locked portion. 


cTimeOut Specifies the time-out period (in milliseconds). If this field is 
NULL, the DosFileIO function continues immediately with the next command. 
If this field is - 1, DosFilelO waits indefinitely for the requested lock to become 
available. Any other value specifies the maximum amount of time DosFileIO 
waits for the requested lock to become available. 


DosFileIO, DosFileLocks, FIOLOCKREC 


New 


typedef struct _FIOLOCKREC { /* flr */ 
USHORT fShare; 
ULONG cbStart; 
ULONG cbLength; 

} FIOLOCKREC; 


The FIOLOCKREC structure contains information used by the DosFileIO func- 
tion for locking a file. This structure is preceded by a FFOLOCKCMD structure’ 
that specifies the number of FIOLOCKREC structures to be used. 


fShare Specifies whether other processes can read the portion of the file that 
is locked. A value of FIO_.SHAREREAD allows other processes to read the 
file; a value of FFOLNOSHARE prevents other processes from reading the file. 


cbStart Specifies the offset of the lock region. The offset is established from 
the beginning of the file. 


cbLength Specifies the length (in bytes) of the region to be locked. 
DosFilelIO, FIOLOCKCMD 


m@ FIOREADWRITE 


Fields 


See Also 


mM FIOSEEKCMD 
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New 


typedef struct _FIOREADWRITE { /*.frweo */ 
USHORT usCmd; 
PVOID pbBuffer; 
USHORT cbBufferLen; 
USHORT cbActualLen; 
} FIOREADWRITE; 


The FIOREADWRITE structure contains information used by the DosFileIO 
function for reading and writing data. 


usCmd_ Specifies the command to pass to the DosFileIO function. This field 
should be set to FIO_READ for a read operation or to FIO_WRITE for a write 
operation. 


pbBuffer Points to the buffer that contains the data to be written, or points to 
a buffer that receives the data that is read. 


cbBufferLen Specifies the length of the buffer (in bytes). 
cbActualLen Specifies the number of bytes actually transferred. 


DosFileIO 


New 


Fields 


See Also 


typedef struct _FIOSEEKCMD { /* fse */ 
USHORT usCmd; 
USHORT fsMethod; 
ULONG ebDistance; 
ULONG cbNewPosition; 
} FIOSEEKCMD; 


The FIOSEEKCMD structure contains information used by the DosFilelO 
function’s seek operation. 


usCmd _ Specifies the command to be passed to the DosFileIO function. This 
field must be set to FIOLSEEK. 


fsMethod Specifies where to begin the seek operation. This field can be one 
of the following values: 


Value Meaning 

FILE_BEGIN Start at the beginning of the file. 
FILE_CURRENT Start at the current location. 
FILE_END Start at the end of the file. 


cbDistance Specifies the new position requested for the file pointer. The 
value of this field is the number of bytes offset from the starting position 
specified in the fsMethod field. 


cbNewPosition On return from the DosFileIO function, this field contains 
the new position of the file pointer relative to the beginning of the file. 


DosChgFilePtr, DosFileIO 
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m™ FIOUNLOCKCMD | New 


Fields 


See Also 


typedef struct  _FIOUNLOCKCMD { /* fuc */ 
USHORT usCmd; 
USHORT cUnlockCnt; 

} FIOUNLOCKCMD; 


The FIOUNLOCKCMD structure contains information used by the DosFileIO 
function for unlocking a file. 


usCmd __ Specifies the command to pass to the DosFileIO function. This field 
must be set to FIOLUNLOCK. 


cUnlockCnt = Specifies the number of FFOUNLOCKREC structures that follow 
this structure. 


DosFileIO, DosFileLocks, FFOUNLOCKREC 


H FIOUNLOCKREC | New 


Fields 


See Also 


typedef struct _FIOUNLOCKREC { /* fur */ 
ULONG ebStart; 
ULONG cbLength; 

} FIOUNLOCKREC; 


The FIOUNLOCKREC structure contains information used by the Dos- 
FileIO function for unlocking a file. This structure is preceded by an 
FIOUNLOCKCMD structure that specifies the number of FFOUNLOCKREC 
structures that are used. 


cbStart Specifies the offset of the unlock region. The offset is determined 
from the beginning of the file. 


cbLength Specifies the length (in bytes) of the region to unlock. 
DosFilelIO, FIOUNLOCKCMD 


mM FONTMETRICS 
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Fields 


Change 
typedef struct _FONTMETRICS { /* fm */ 
CHAR szFamilyname [FACESIZE]; 
CHAR szFacename [FACESIZE]; 


USHORT idRegistry; 
USHORT usCodePage; 


LONG 1EmHeight; 

LONG 1XHeight; 

LONG 1MaxAscender; 
LONG 1MaxDescender; 
LONG lLowerCaseAscent; 
LONG lLowerCaseDescent; 
LONG lInternalLeading; 
LONG 1ExternalLeading; 
LONG lAveCharWidth; 
LONG 1MaxCharInc; 

LONG 1EmInc; 

LONG 1MaxBaselineExt; 


SHORT sCharSlope; 

SHORT sInlineDir; 

SHORT sCharRot; 

USHORT usWeightClass; 
USHORT usWidthClass; 
SHORT sXDeviceRes; 

SHORT sYDeviceRes; 

SHORT sFirstChar; 

SHORT sLastChar; 

SHORT sDefaultChar; 
SHORT sBreakChar; 

SHORT sNominalPointSize; 
SHORT sMinimumPointSize; 
SHORT sMaximumPointSize; 
USHORT  fsType; 

USHORT fsDefn; 

USHORT fsSelection:; 
USHORT fsCapabilities; 


LONG 1SubscriptXSize; 
LONG lSubscriptyYSize; 
LONG lSubscriptXOffset; 
LONG lSubscriptYOffset; 
LONG lSuperscriptXSize; 
LONG lSuperscriptYSize; 
LONG lSuperscriptXxOffset; 
LONG lSuperscriptYOffset; 
LONG lUnderscoreSize; 
LONG l1UnderscorePosition; 
LONG 1StrikeoutSize; 

LONG 1StrikeoutPosition; 


SHORT sKerningPairs; 
SHORT sFamilyClass; 
LONG lMatch; 

} FONTMETRICS; 


The FONTMETRICS structure contains information about fonts. 


szFamilyname[FACESIZE] Specifies the family name of the font. Examples 
of common family names in MS OS/2 version 1.1 are Courier, Helvetica, and 
Times. 


szFacename[FACESIZE] Specifies the typeface name of the font. Examples 
of common typeface names are Courier, Helvetica, and Times. 


idRegistry Specifies the registry number of the font. For MS OS/2 version 
1.1, this value must be zero. 


usCodePage Identifics the code page an application should use with a partic- 
ular font. For MS OS/2 version 1.1, this value must be 850. 
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lIEmHeight Specifies the average height of uppercase characters. The height is 
measured in world coordinates from the baseline to the top of the character. 


IXHeight Specifies the average height of lowercase characters. The height is 
measured in world coordinates from the baseline to the top of the character. 


IMaxAscender Specifies the maximum height of any character in the font. 
The height is measured in world coordinates from the baseline to the top of the 
character. 


IMaxDescender Specifies the maximum depth of any character in the font. 
The depth is measured in world coordinates from the baseline to the bottom of 
the lowest character. 


ILowerCaseAscent Specifies the maximum height of any lowercase character 
in the font. The height is measured in world coordinates from the baseline to the 
top of the ascender of the tallest lowercase character. 


ILowerCaseDescent Specifies the maximum depth of any lowercase charac- 
ter in a font. The depth is measure in world coordinates from the baseline to the 
bottom of the descender on the lowest lowercase character. 


IInternalLeading Specifies the amount of space reserved in the top of each 
character cell for accent marks. This metric is always given in world coordinates. 


lExternalLeading Specifies the amount of space that should appear between 
adjacent rows of text. This metric is always given in world coordinates. 


IAveCharWidth Specifies the average character width for characters in the 
font. The average character width is determined by multiplying the width of each 
lowercase character by a predetermined constant, adding the results, and then 
dividing by 1000. Letters and their predetermined constances are listed as fol- 
lows: 


a 64 j 3 s 56 

b 14 k 6 t 71 
oe 27 1 35 u 31 

d 35 m 20 Vv 10 

e 100 n 56 Ww 18 

f 20 o 8656 xX 3 

g 14 p 17 y 18 

h 42 q 4 Zz 2 

i 63 r 49 space 166 


IMaxCharIne Specifies the maximum increment between characters in the 
font. 


lIEmInc Specifies the width of an uppercase M in the font. 


IMaxBaselineExt Specifies the sum of the maximum ascender and maximum 
descender values. 


sCharSlope Specifies the angle (in degrees and minutes) between a vertical 
line and the upright strokes in characters in the font. The first nine bits of this 
value contain the degrees, the next six bits contain the minutes, and the last bit 
is reserved. The slope of characters in a normal font is zero; the slope of italic 
characters is nonzero. 
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sInlineDir Specifies an angle (in degrees and minutes, increasing clockwise) 
from the x-axis that the system uses when it draws a text string. The system 
draws each consccutive character from the text string in the inline direction. The 
inline-direction angle for a Swiss font is zero; the inline direction for a Hebrew 
font is 180. 


sCharRot Specifies the angle (in degrees and minutes) between the baseline 
of characters in the font and the x-axis. This is the angle assigned by the font 
designer. 


usWeightClass Specifies the thickness of the strokes that form the characters 
in the font. This field can be one of the following values: 


‘Value Meaning 


Ultra-light 
Extra-light 
Light 
Semi-light 
Medium (normal) 
Semi-bold 
Bold 
Extra-bold 

~ Ultra-bold 


oon A un Ff WN KF 


usWidthClass Specifies the relative-aspect ratio of characters in the font in 
relation to the normal-aspect ratio for a font of this type. The following are the 
possible values: 


Value Description Normal aspect ratio 
1 Ultra-condensed 50% 

2 Extra-condensed 2.5% 

3 Condensed 715% 

4 Semi-condensed 87.5% 

5 Normal 100% 

6 Semi-expanded 112.5% 

7 Expanded 125% 

8 Extra-expanded 50% 

9 Ultra-expanded 200% 


sXDeviceRes Specifies the horizontal resolution of the target device for 
which the font was originally designed. This value is given in pels per inch. 


sYDeviceRes Specifies the vertical resolution of the target device for which 
the font was originally designed. This value is given in pels per inch. 


sFirstChar Specifies the code point for the first character in the font. 


sLastChar Specifies the code point for the last character in the font. This 
code point is an offset from the sFirstChar value. 
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sDefaultChar Specifies the code point for the default character in the font. 
This code point is an offset from the sDefaultChar value. The default character 
is the character the system uses when an application specifies a code point that 
is out of the range of a font’s code page. 


sBreakChar Specifies the code point for the space character in the font. This 
code point is an offset from the sFirstChar value. 


sNominalPointSize Specifies the height of the font (in decipoints—each deci- 
point is 1/720 inch). The nominal point size is the point size the font was 
designed to be drawn. 


‘sMinimumPointSize Specifies the mimimum height of the font (in deci- 


points). A font should not be reduced to a size smaller than the minimum point 
size. ; 


sMaximumPointSize Specifies the maximum height of the font (in deci- 
points). A font should not be increased to a size larger than this value. 


fsType Specifies the type of font. This field can be one or more of the follow- 
ing values: 


Value Meaning 

FM_TYPE_FIXED Font is fixed. Font is proportional if this value is 
not specified. 

FM_TYPE_LICENSED Font is licensed. 

FM_TYPE_KERNING Font has kerning information. 


FM_TYPE_DBCS Font is a double-byte character set. 
FM_TYPE_MBCS Font is a multiple-byte character set. 
FM_TYPE_64K Font requires more than 64K of memory. 


fsDefn Specifies the definition of the font. This field can be one or more of 
the following values: 


Value Meaning 


FM_DEFN_OUTLINE Specifies an outline font (vector). 
FM_DEFN_GENERIC Specifies a generic font (raster or bitmapped). 


fsSelection Specifies how the characters are to be drawn. This field can be 
one or more of the following values: 


Value Meaning 

FM_SEL_ITALIC Characters are italic. 
FM_SEL_UNDERSCORE Characters are underscored. 
FM_SEL_NEGATIVE Characters are drawn using negative images. 


FM_SEL_OUTLINE Characters are outlined. 
FM_SEL_STRIKEOUT Characters are overstruck. 
FM_SEL_BOLD Characters are bold. 


fsCapabilities Specifies whether the characters in this font can be mixed with 
graphics. If this field is FA_CAP_NOMIKX, the characters cannot be mixed with 
graphics; otherwise, they can be mixed with graphics. 
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ISubscriptXSize Specifies the horizontal side (in world coordinates) for sub- 
scripts in the font. 


ISubscriptYSize Specifies the vertical size (in world coordinates) for sub- 
scripts in the font. 


ISubscriptXOffset Specifies the horizontal offset from the left edge of the 
character cell. 


ISubscriptYOffset Specifies the vertical offset from the character-cell 
baseline. 


ISuperscriptXSize Specifies the horizontal size (in world coordinates) for 
superscripts in the font. 


ISuperscriptYSize Specifies the vertical size (in world coordinates) for super- 
scripts in the font. 


ISuperscriptXOffset Specifies the horizontal offset from the left edge of the 
character cell. 


ISuperscriptYOffset Specifies the vertical offset from the character-cell 
baseline. 


IUnderscoreSize Specifies the width of the underscore (in world coor- 
dinates). 


IUnderscorePosition Specifies the distance from the baseline to the under- 
score line (in world coordinates). 


IStrikeoutSize Specifies the width of the overstrike (in world coordinates). 


IStrikeoutPosition Specifies the position of the overstrike in relation to the 
baseline. 


sKerningPairs Specifies the number of kerning pairs in the kerning-pair table 
for the font. 


sFamilyClass Specifies the font-family class and subclass. 


IMatch Specifies a long integer value that should be copied to the FATTRS 
structure when the GpiCreateLogFont function is called. (When this value is 
passed, the system must select a font that contains the metrics associated with 
this IMatch field.) 


See Also GpiCreateLogFont, GpiQueryFontMetrics, GpiQueryFonts, VioQueryFonts 


Changes New constants have been added for the fsType, fsDefn, and fsSelection fields. 
The sReserved ficld has been replaced by the sFamilyClass field. 


m@ FSINFO Change 


typedef struct _FSINFO { /* fsint */ 
ULONG ulVSN; 
VOLUMELABEL vol; 

} FSINEO; 


The FSINFO structure contains information about the volume label of a disk. 
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Fields 


See Also 
Changes 


mM FSQBUFFER 


Fields 


ulVSN Specifies the serial number of the disk. If there is no serial number on 
the disk, this field is zero. 


vol Specifies a VOLUMELABEL structure that will contain the name of the 
volume label. 


DosQFSInfo, VOLUMELABEL 


The fields fdateCreation and ftimeCreation worked only for MS OS/2, version 
1.1. These fields have been replaced by the ulVSN field, which receives the serial 
number of the disk for MS OS/2, version 1.2. 


New 


typedef struct _FSQBUFFER { /* fsqbf */ 
USHORT iType; 
USHORT cbName; 
UCHAR szName[1]; 
USHORT cbESDName; 
UCHAR szESDName [1]; 
USHORT cbESAData; 
UCHAR rgFSAData[1]; 
} ESQBUFEER; 


The FSQBUFFER structure contains information about the file system attached 
to a driver or device. 


iType Specifies the type of device. This field can contain one of the following 
values: 


Value Type 

FSAT_CHARDEV Resident character device 
FSAT_PSEUDODEV Pseudo-character device 
FSAT_LOCALDRV Local drive 


FSAT_REMOTEDRV Remote drive attached to a file system 


cbName_ Specifies the length of the drive or device name, not including the 
null terminating character. 


szName[1] Specifies the drive or device name. The actual length of this field 
varies, depending on the length of the device name. 


cbFSDName Specifies the length of the file-system name, not including the 
null terminating character. 


szFSDName[1] Specifies the file-system name the drive or device is attached 
to. The actual length of this field varies depending on the length of the file- 
system name. This field contains only a null character if the device is a resident 
character device. 


cbFSAData Specifies the length of the data returned by the file system. 


rgFSAData[1] Specifies the data returned by the file system. The actual 
length and meaning of this field varies, depending on the file system that is 
attached. 


Comments 


See Also 


GEA 


Fields 


See Also 


GEALIST 
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This structure should be used only as a guideline. Because it contains variable- 
length fields, it cannot be used directly to retrieve the data. 


DosQFSAttach 


New 


typedef struct _GEA { /* gea */ 
BYTE cbName; 
CHAR szName[1}; 

} GEA; 


The GEA structure contains an extended-attribute name. 


cbName _ Specifies the length of the extended-attribute name contained in the 
szName field, not including the null terminating character. 


szName[1] Contains the extended-attribute name. 


EAOP, FEA, GEALIST 


New 


Fields 


Comments 


See Also 


typedef struct _GEALIST { /* geal */ 
ULONG cbList; 
GEA list([1]; 

} GEALIST; 


The GEALIST structure contains one or more extended-attribute names. 


cbList Specifies the size (in bytes) of the structure. 


list{1]_ Contains an array of one or more GEA structures. 


The GEALIST structure contains a list of extended-attribute names to retrieve 


' information for. The FEALIST structure contains a list of extended attributes 


that were found. 


DosFindFirst2, DosMkDir2, DosOpen2, neers DosSetFileInfo, Dos- 
SetPathInfo, EAOP, FEALIST, GEA 
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mM HCINFO Correction 
typedef struct _HCINFO { /* hei */ 
CHAR szFormname [32]; 
LONG Cx; 
LONG cy; 
LONG xLeftClip; 
LONG yBottomClip; 
LONG xRightClip; 
LONG yTopClip; 
LONG xPels; 
LONG yPels; 
LONG flAttributes; 
} HCINEFO; 
The HCINFO structure contains information about the hard-copy capabilities of 
a device. 
Fields szFormname[32] Specifies the form name. 
cx Specifies the form width (in millimeters). 
cy Specifies the form height (top to bottom, in millimeters). 
xLeftClip Specifies the left clip limit (in millimeters). 
yBottomClip Specifies the bottom clip limit (in millimeters). 
xRightClip Specifies the right clip limit (in millimeters). 
yTopClip Specifies the top clip limit (in millimeters). 
xPels Specifies the number of pels between the left and right clip limits. 
yPels Specifies the number of pels between the top and bottom clip limits. 
flAttributes Specifies whether the given form is the selected form. This field 
is HCAPS_CURRENT if the form is selected. Otherwise, it is zero. 
See Also DevQueryHardcopyCaps 
Corrections The flAttributes field is set to HCAPS_CURRENT when the specified form is 
the selected form. 
M@ HELPINIT New 
typedef struct _HELPINIT { /* hinit */ 
USHORT cb; 
ULONG ulReturnCode; 
PSZ pszTutorialName; 
PHELPTABLE phtHelpTable; 
HMODULE hmodHelpTableModule; 
HMODULE hmodAccelActionBarModule; 
USHORT idAccelTable; 
USHORT idActionBar; 
PSZ pszHelpWindowTitle; 
USHORT usShowPanelld; 
PSZ pszHelpLibraryName; 
} HELPINIT; 


The HELPINIT structure is used when creating a help instance for an applica- 
tion. 


Fields 


See Also 


mM HELPTABLE 
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cBytes Specifies the number of bytes in the initialization structure. 


ulReturnCode Specifies the value returned by the system at initialization. A 
value of zero means that initialization was successful. 


pszTutorialName Points to the string that contains the default tutorial name. 
If this field is NULL, the application does not have a tutorial or the tutorial 
name is specified in each help library. 


phtHelpTable Points to the help table or to the resource ID of the help 
table. If you defined the table in a resource file, the low word should contain the 
resource ID of the table and the high word must be OxFFFF. 


hmodHelpTableModule Identifies the module handle returned by the 
DosLoadModule function when the application loaded the resource file. A value 
of NULL indicates that the resource file that contains the help table was 
appended to the application’s executable (.exe) file. 


hmodAccelActionBarModule Identifies the dynamic-link library that con- 
tains the accelerator table and menu-bar template used by a help window. A 
value of NULL indicates that the resource file containing the tailored accelerator 
table and menu bar was appended to the application’s executable (.exe) file. 


idAccelTable Identifies the accelerator table. The accelerator table is found 
in the dynamic-link library identified by the hmodAccelActionBarModule field. 
If the default accelerator table is to be used, this field should be NULL. 


idActionBar Identifies the menu-bar template used by a help window. The 
menu-bar template is found in the dynamic-link library identified by the hmod- 
AccelActionBarModule field. If the default menu bar is to be used, this field 
should be NULL. 


pszHelpWindowTitle Points to the string that contains the window title of 
each help window. 


usShowPanelld Specifies whether to display the window (panel) ID on a help 
window. If this value is CMIC_HIDE_PANEL_ID, the window ID is not shown; 
if this value is CMIC_SHOW_PANEL_ID, the window ID is shown. 


pszHelpLibraryName Points to the string that contains the name of the help 
library that the system searches on each help request. 


WinCreateHelpInstance, HELPTABLE 


Fields 


New 
typedef struct _HELPTABLE { /* ht */ 
USHORT idAppWindow; 
PHELPSUBTABLE phstHelpSubTable; 
USHORT idExtPanel; 


} HELPTABLE; 
The HELPTABLE structure identifies the help table for a specified application. 


idAppWindow Specifies the window ID of a frame or dialog window. 


phstHelpSubTable Points to a help subtable. The help subtable contains 
help panel IDs for the child windows and/or menus in the specified window. 
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Comments 


See Also 


— KBDHWID 


idExtPanel Specifies an extended help panel ID. This help panel is displayed 
whenever extended help for the specified window is requested. 


The help table for an application usually consists of an array of two or more 
HELPTABLE structures. Each structure specifies one window, such as a frame 
or dialog window, and points to one subtable containing the help panel IDs for 
each item in the window that the user may request help for. To mark the end of 
the array, the last structure in the array must be zero-filled. 


The help subtable, pointed to by the phstHelpSubTable field, is an array help 
panel IDs and window or menu IDs. The first element in the help subtable, a 
16-bit integer, specifies the size, in 16-bit words, of each subsequent element. 
The system requires that the first element be at least 2. All subsequent elements 
consist of the number of words specified by the first element. The first word in 
an element must be a window or menu ID. The second word must be a help 
panel ID. Any additional words are not used by the system. The last element in 
the help subtable must be zero-filled. 


HM_CREATE_HELP_TABLE 


New 


Fields 


See Also 


typedef struct _KBDHWID { /* kbhw */ 
USHORT cb; 
USHORT idKbd; 
USHORT usReservedl; 
USHORT usReserved2; 
} KBDHWID; 


The KBDHWID structure contains information that identifies keyboard 
hardware. 


cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


idKbd Specifies the ID number generated by the keyboard hardware. This 
field can be one of the following values: 


Keyboard Value 
KEYBOARD_AT_COMPATABLE IBM PC/AT or compatible keyboard 
KEYBOARD_ENHANCED._101 101-key enhanced keyboard 
KEYBOARD_ENHANCED_102 102-key enhanced keyboard 
KEYBOARD_ENHANCED_122 122-key enhanced keyboard 
KEYBOARD_SPACESAVER Space Saver enhanced keyboard 


usReservedl Specifies a reserved value. 
usReserved2 Specifies a reserved value. 


KbdGetHWID 


mM KBDKEYINFO 


Fields 
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Change 


typedef struct _KBDKEYINEFO { /* kboi */ 
UCHAR chChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNlsShift; : 
USHORT fsState; 
ULONG time; 
} KBDKEYINFO; 


The KBDKEYINFO structure contains information about the last key pressed. 


chChar Specifies the character derived from translation of the chScan field. 


chScan Specifies the scan code received from the keyboard, identifying the 
key pressed. This scan code may be modified during the translation process. 


fbStatus Specifies the state of the retrieved scan code. It can be any combina- 
tion of the following values: 


Value Meaning 


SHIFT_KEY_IN Shift key is received (valid only in binary 
mode when shift reporting is turned on). 


CONVERSION_REQUEST Conversion requested. 


FINAL_CHAR_IN Final character received. 

INTERIM_CHAR_IN Interim character received. 

EXTENDED_CODE The scan code is an extended code, not a 
character. 


bNisShift Specifies a reserved value; must be zero. 


fsState Specifies the state of the shift keys. It can be any combination of the 
following values: 


Value Meaning 

RIGHTSHIFT Right SHIFT key down. 
LEFTSHIFT Left SHIFT key down. 
CONTROL Either CONTROL key down. 
ALT Either ALT key down. 
SCROLLLOCK_ON SCROLL LOCK mode turned on. 
NUMLOCK_ON NUMLOCK mode turned on. 
CAPSLOCK_ON CAPSLOCK mode turned on. 
INSERT_ON INSERT key turned on. 
LEFTCONTROL Left CONTROL key down. 
LEFTALT Left ALT key down. 
RIGHTCONTROL Right CONTROL key down. 
RIGHTALT Right ALT key down. 


SCROLLLOCK _ SCROLL LOCK key down. 
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Value Meaning 
NUMLOCK NUMLOCK key down. 
CAPSLOCK CAPSLOCK key down. 
SYSREQ SYSREQ key down. 


time Specifies the time stamp of the keystroke (in milliseconds). 
See Also KbdCharIn, KbdPeek, KBD_PEEKCHAR 


Changes EXTENDED_CODE is a possible value for the fsStatus field and indicates the 
scan code is an extended code, not a character. 


LDTADDRINFO New 


typedef struct _LDTADDRINFO { /* ldtaddr */ 
PULONG pulPhysAddr; 
USHORT cb; 

} LDTADDRINFO; 


The LDTADDRINFO structure holds information about an address to be added 
to the local descriptor table (LDT). 


Fields pulPhysAddr Points to the 32-bit physical address of the bepianing of the 
block of memory for which an LDT selector is requested. 


cb Specifies the number of bytes for the requested memory. 


See Also SCR_ALLOCLDT, SCR_ALLOCLDTOFF 
LINFOSEG Change 
typedef struct _LINFOSEG { /* lis */ 
PID pidCurrent; 
PID pidParent; 
USHORT prtyCurrent; 
TID tidCurrent; 


USHORT sgCurrent; 
UCHAR rfProcStatus; 
UCHAR dummy1; 
BOOL fForeground; 
UCHAR typeProcess; 
UCHAR dummy 2; 
SEL selEnvironment; 
USHORT offCmdLine; 
USHORT cbDataSegment; 
USHORT cbStack; 
USHORT cbHeap; 
HMODULE hmod; 
SEL selDS; 

} LINFOSEG; 


The LINFOSEG structure contains information local to the current process. 


Fields pidCurrent Specifies the identifier of the current process. 
pidParent Specifies the identifier of the parent process. 


Comments 


See Also 
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prtyCurrent Specifies the priority of the current thread. 
tidCurrent Specifies the identifier of the current thread. 
sgCurrent Specifies the current screen group. 


rfProcStatus Specifies the process status. A value of PS_EXITLIST indi- 
cates the process is in an exit-list routine. 


dummyl __ Reserved. 
fForeground Specifics that the current process is in foreground. 
typeProcess Specifies the process type. It can be one of the following values: 


Value Meaning 

PT_DETACHED Process is running as a detached process. 

PT_FULLSCREEN Process is running in a full-screen protected-mode 
session. 

PT_PM Process is running in the Presentation Manager 
screen group. 

PT_REALMODE Process is running in DOS-compatibility mode. 


PT_WINDOWABLEVIO Process is running in a VIO-window session. 


dummy2_ Reserved. 


selEnvironment Specifies the selector to the application’s copy of the 
environment. 


offCmdLine Specifies the offset to the environment where the command line 
that is used to run the current.application is copied. 


cbDataSegment Specifies the size of the default data segment. 
cbStack Specifies the size of the stack. 

cbHeap Specifies the size of the heap. 

hmod Identifies the program. 

selDS Specifies the default data segment. 


The following fields are contained in registers at start up: 


Field Register 
SelEnvironment ax 
offCmdLine bx 
‘cbDataSegment cx 
cbStack dx 
cbHeap si 

hmod di 

selIDS ds 


DosGetInfoSeg, GINFOSEG 
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Changes 


Corrections 


B® MATRIXLF 


The PT_.FULLSCREEN, PT_.REALMODE, PT_.WINDOWABLEVIO, PT_PM, 
and PT_DETACHED constants replace the numeric values previously defined 
for the typeProcess field. The constant PS_EXITLIST is a valid value for the 
rfProcStatus field. 


The rfProcStatus specifies the process status, not the subscreen group. 


Correction 


typedef struct _MATRIXLF { 7* matlf */ 
FIXED f£xM1i; 
FIXED £xM12; 
LONG 1Mi13; 
FIXED f£xM21; 
FIXED £xM22; 
LONG 1M23; 


LONG 1M31; 

LONG 1M32; 

LONG 1M33; 
} MATRIXLE; 


The MATRIXLF structure contains the scaling, translation, rotation, shear, and 
reflection transformation values that MS OS/2 uses when your application calls 
one of the transformation functions. 


If the matrix contains scaling transformation values, the following fields are set: 


Field Description 
fxM11 Specifies the horizontal scaling value. 
fxM22 Specifies the vertical scaling value. 


If the matrix contains translation transformation values, the following fields are 
set: 


Field Description 
IM31 Specifies the horizontal translation value. 
IM32 Specifies the vertical translation value. 


If the matrix contains rotation transformation values, the following fields are set: 


Field Description 

fxM11 Specifies the cosine of the angle of rotation. 
fxM12 Specifies the negative sine of the angle of rotation. 
fxM21 Specifies the sine of the angle of rotation. 

fxM22 Specifies the cosine of the angle of rotation. 


If the matrix contains vertical-shear transformation values, the following fields 
are set: 


Field Description 


fxM21 Specifies the horizontal shear value. 


fxM22 Specifies the vertical shear value. 


See Also 


Corrections 
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If the matrix contains horizontal-shear transformation values, the following fields 
are set: 


Field Description 
fxM11 Specifies the horizontal-shear value. 
fxM12 Specifies the vertical-shear value. 


If the matrix contains reflection values, the following fields are set: 
Field Description 


fxM11 Specifies the vertical-reflection value. (This value is always 
negative. It causes reflection about the x-axis.) 


fxM22 Specifies the horizontal-reflection value. (This value is 
always negative. It causes reflection about the y-axis.) 


GpiCallSegmentMatrix, GpiQueryDefault ViewMatrix, GpiQueryModel- 
TransformMatrix, GpiQuerySegmentTransformMatrix, GpiQueryViewing- 
TransformMatrix, GpiSetDefault ViewMatrix, GpiSetModelTransformMatrix, 
GpiSetSegmentTransformMatrix, GpiSet ViewingTransformMatrix 


If the matrix contains scaling transformation values, the fxM2z2 field contains the 
vertical scaling value, not the fxM12 field. 


M MLE_SEARCHDATA | New 


Fields 


typedef struct _MLE_SEARCHDATA { /* miesrch */ 
USHORT cb; 
PCHAR pchFind; 
PCHAR pchReplace; 
SHORT cchFind; 
SHORT cchReplace; 
IPT iptStart; 
IPT iptStop; 
USHORT cchFound; 
} MLE_SEARCHDATA; 


The MLE_SEARCHDATA structure contains information required to perform a 
search of a multiple-line entry field (MLE) using the MLM_SEARCH message. 


cb Specifies the size of the structure (in bytes). The size depends on the 
operating-system version. Programs written in the C language should use the 
sizeof operator to set this field. 


pehFind Points to the null-terminated string to find. 
pchReplace Points to the null-terminated replacement string. 


cchFind Specifies the number of characters to delete in the search string 
before inserting the replacement string. This field is used only if the 
MLFSEARCH_CHANGEALL flag is specified in the MLM_SEARCH mes- 
sage. 
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Comments 


See Also 


— MLECTLDATA 


echReplace Specifies the number of replacement-string characters to insert in 
the MLE text. This field is used only if the MLFSEARCH_CHANGEALL flag 
is specified in the MLM_SEARCH message. 


iptStart Specifies the offset (number of characters from the beginning of the 
text) of the first character to search. A value of - 1 causes the search to start at 
the current cursor position. 


iptStop Specifies the offset of the last character to search. A negative value 
causes the search to end at the end of the text. 


cchFound Specifies the length (in characters) of the string found. 

If the iptStop field is less than the iptStart field, the search wraps to the begin- 
ning of the text. If the two fields are identical, all the text in the MLE is 
searched. 


MLM_SEARCII 


New 


Fields 


typedef struct _MLECTLDATA { /* mlectl */ 
USHORT cbCtlData; 
USHORT afIEFormat; 
ULONG cchText; 
IPT iptAnchor; 
IPT iptCursor; 
LONG cxFormat; 
LONG cyFormat; 
ULONG afFormatFlags; 
} MLECTLDATA; 


The MLECTLDATA structure contains multiple-line are (MLE) format 
information. 


-cbCtlIData Specifies the size of the structure (in bytes). Programs written in 


the C language should use the sizeof operator to set this field. 


affEFormat Specifies the import/export format. This parameter is be one of 
the following values: 


Value Meaning 


MLFIE_CFTEXT Specifies the clipboard text format. This 
format uses carriage-return/linefeed char- 
acters for line breaks on export, and 
recognizes linefeed, carriage-return/ 
linefeed, or linefeed/carriage-return char- 
acters for line breaks on import. This is 
the default format. 


MLFIE_NOTRANS Specifies a format that uses linefeed char- 
acters for line breaks. Guarantees that any 
text imported into the MLE in this form 
can be recovered in exactly the same form 
on export. 


MLECTLDATA = 389 


Value Meaning 


MLFIE_WINFMT Specifies the format of the MLE window. 
This format recognizes carriage-return/ 
linefeed characters for line breaks on 
import. It ignores the sequence carriage- 
return/carriage-return/linefeed. On export, 
it uses carriage-return/linefeed characters 
to denote a hard line break and carriage- 
return/carriage-return/linefeed character to 
denote a soft line break caused by word- 
wrapping. 


cchText Specifies the maximum amount (in bytes) of text. 


iptAnchor Specifies the offset (number of characters from the beginning of 
the text) of the first character of the selection. 


iptCursor Specifies the offset of the cursor position (one character to the 
right of the selection). 


exFormat Specifies the width (in pels) of the format rectangle. 
cyFormat Specifies the height (in pels) of the format rectangle. 


afFormatFlags Specifies how the format rectangle is to be treated. This 
parameter can be one or more of the following flags: 


Value Meaning 


MLFFMTRECT_LIMITHORZ Specifies that the text within the 
MLE cannot exceed the horizontal 
dimension specified by the cxFormat 
field. If word-wrap mode is turned 
on when the format rectangle is set, 
lines automatically wrap to stay 
within the horizontal limit of the 

format rectangle. If word-wrap 
mode is turned off when the 
format rectangle is set, an 
MLN_PIXHORZOVERFLOW 
notification message is sent to the 
application whenever an operation 
would exceed the horizontal limit 
specified in the format rectangle. 


MLFFMTRECT_LIMITVERT Specifies that the text within the 
MLE cannot exceed the vertical 
dimension specified by the 
cxFormat field. Whenever an 
MLE operation would cause text 
to exceed the vertical limit, an 
MLN_PIXVERTOVERFLOW 
notification message is sent to the 
application. 
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Value Meaning 


MLFFMTRECT_MATCHWINDOW Specifies that the format rectangle is 
to be kept the same size as the MLE 
window (minus the border or scroll 
bars). 


MLFFMTRECT_FORMATRECT Specifies that the format rectangle is 
to be kept the same size as the MLE 
window (minus the border or scroll 
bars) and that text cannot exceed the 
size of the window. This value is 
equivalent to combining the values 
MLFFMTRECT_LIMITHORZ, 
MLFFMTRECT_LIMITVERT, and 
MLFFMTRECT_MATCHWINDOW. 


See Also MLM_FORMAT, MLM_SETFORMATRECT 
MLEFORMATRECT New 
typedef struct _MLEFORMATRECT { /* milefrd +) 


LONG cxFormat; 
LONG cyFormat; 
} MLEFORMATRECT; 


The MLEFORMATRECT structure contains width and height information for 
the multiple-line entry-field (MLE) format rectangle. 


Fields cxFormat Specifies the width (in pels) of the MLE format rectangle. If this 
field is - 1, the current MLE-window width (minus any border or scroll bars) is 
used. If this field is 0, there is no limit on the MLE width. 


cyFormat Specifies the height (in pels) of the format rectangle. If this field is 
- 1, the current MLE-window height (minus any border or scroll bars) is used. If 
this field is 0, there is no limit on the MLE height. 


See Also MLM_QUERYFORMATRECT, MLM_SETFORMATRECT 
MLEMARGSTRUCT New 
typedef struct _MLEMARGSTRUCT { /* miemrg */ 


USHORT afMargins; 
USHORT usMouMsg; 
IPT iptNear; 

} MLEMARGSTRUCT; 


The MLEMARGSTRUCT structure contains data used by the MLN_MARGIN 
message to notify an application when the user moves the mouse to one of the 
margins. 


Fields 


See Also 
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afMargins Specifies the margin. This field can be one of the following values: 


Value 


MLFMARGIN_LEFT 


MLFMARGIN_RIGHT 


MLFMARGIN_TOP 


MLFMARGIN_BOTTOM 


Meaning 

The mouse was moved over the left 
margin. 

The mouse was moved over the right 
margin. 

The mouse was moved over the top 
margin. 


The mouse was moved over the bottom 
margin. 


usMouMsg Specifies the mouse message associated with the move. 


iptNear Specifies the offset (number of characters from the beginning of the 
text) of the character nearest to the mouse. 


MLN_MARGIN, WM_CONTROL 


mM MLEOVERFLOW 


New 


Fields 


typedef struct _MLEOVERFLOW { 


ULONG afErrind; 

LONG nBytesOver; 

LONG pixHorzOver; 

LONG pixVertOver; 
} MLEOVERELOW; 


/* mleovr */ 


The MLEOVERFLOW structure contains information about overflow in a 


multiple-line entry field (MLE). 


afErrInd Specifies the cause of the error. This parameter can be one of the 


following values: 
Value 


MLFEFR_RESIZE 


MLFEFR_TABSTOP 


MLFEFR_FONT 


MLFEFR_TEXT 


MLFEFR_WORDWRAP 


MLFETL_TEXTBYTES 


Meaning 


The overflow was the result of a resize 
operation that overflowed a format rect- 
angle. 


The overflow was the result of resetting 
tab stops that overflowed a format rect- 
angle. 


The overflow was the result of changing 
font information. 


The overflow was the result of a text inser- 
tion operation with the format rectangle 
set. 


The overflow was the result of setting word 
wrap while the MLE text exceeds the for- 
mat rectangle. 


The overfiow was the result of a text inser- 
tion operation with the text limit set. 
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See Also 


m PARAM 


nBytesOver 
pixHorzOver 
pixVertOver 


Specifies the number of bytes that overflowed. 


Specifies the number of pels that overflowed horizontally. 
Specifies the number of pels that overflowed vertically. 


MLN_OVERFLOW, WM_CONTROL 


New 


Fields 


typedef struct _PARAM { 


ULONG id; 
ULONG cb; 


/* param */ 


BYTE ab[1]; 


} PARAM; 


The PARAM structure contains a presentation parameter. 


id Identifies the presentation parameter. It can be one of the following values: 


Value 


PP_FOREGROUNDCOLOR 
PP_FOREGROUNDCOLORINDEX 


PP_BACKGROUNDCOLOR 
PP_BACKGROUNDCOLORINDEX 


PP_HILITEFOREGROUNDCOLOR 
PP_HILITEFOREGROUNDCOLORINDEX 
PP_HILITEBACKGROUNDCOLOR 
PP_HILITEBACKGROUNDCOLORINDEX 
PP_DISABLEDFOREGROUNDCOLOR 
PP_DISABLEDFOREGROUNDCOLORINDEX 
PP_DISABLEDBACKGROUNDCOLOR 
PP_DISABLEDBACKGROUNDCOLORINDEX 
PP_BORDERCOLOR 


PP_BORDERCOLORINDEX 


Meaning 


RGB foreground color 


Color index of foreground 
color 


RGB background color 


Color index of background 
color 


RGB color of foreground 
highlighted area 
Color index of foreground 
highlighted area 
RGB color of background 
highlighted area 


Color index of background 
highlighted area 


RGB foreground disabled 
color 


Color index of foreground 
disabled color 


RGB color of background 
disabled color 


Color index of background 
disabled color 


RGB color of window 
border 


Color index of window 
border 
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Value Meaning 
PP_FONTNAMESIZE Font size. 
PP_FONTHANDLE Font handle 


A value of zero for this parameter specifies an application-defined string. 
cb Specifies the length of the presentation parameter. 


ab[1] Specifies an array of bytes containing the presentation parameter. 
See Also PRESPARAMS 


m@ PIPESEMSTATE New 


typedef struct _PIPESEMSTATE { /* nmpsmst */ 
BYTE fStatus; 
BYTE fFlag; 
USHORT usKey; 
USHORT usAvail; 
} PIPESEMSTATE; 


The PIPESEMSTATE structure contains named-pipe information retrieved by 
using the DosQNmPipeSemState function. 


Fields fStatus Specifies the status of the named pipe. This field can be one of the 
following values: 
Value Meaning 
NPSS_EOI End of information. 


NPSS_RDATA Readable data is available. 
NPSS_WSPACE Write space is available. 
NPSS_CLOSE Pipe is in closing state. 


fFlag Specifies additional information. If this field is NPSS_WAIT, there is a 
waiting thread on the end of the pipe. 


usKey Specifies the user’s key value. 


usAvail Specifies the available data if the fStatus field is NPSS_RDATA, or 
the available space if the fStatus field is NPSS_WSPACE. 


See Also DosQNmPipeSemState 
m™ PRESPARAMS New 
typedef struct _PRESPARAMS { /* pres */ 
ULONG cb; 


PARAM aparam[1]; 
} PRESPARAMS; 


The PRESPARAMS structure contains an array of PARAM structures that con- 
tain presentation parameters. 


Fields 


See Also 


PRFPROFILE 


Fields 


See Also 


PROGDETAILS 
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cb Specifies the size (in bytes) of the structure, including the array of PARAM 
structures. 


aparam[1] 


PARAM 


Specifies an array of one or more PARAM structures. 


New 


typedef struct _PRFPROFILE { 
ULONG cchUserName; 
PSZ pszUserName; 
ULONG cchSysName; 
PSZ pszSysName; 

} PREPROFILE; 


/* prfpro */ 


The PRFPROFILE structure specifies the names of files that contain profile 
information. 


cchUserName Specifies the number of characters in the string pointed to by 
the pszUserName field. 


pszUserName Points to the null-terminated string that contains the name of 
the file used to store user-profile information. 


echSysName Specifies the number of characters in the string pointed to by 
the pszSysName field. 


pszSysName Points to the null-terminated string that contains the name of 
the file used to store system-profile information. 


PrfQueryProfile, PrfReset 


New 


Fields 


typedef struct _PROGDETAILS { 
ULONG Length; 
PROGTYPE progt; 
USHORT padi[3]; 
PSZ pszTitle; 
PSZ pszExecutable; 
PSZ pszParameters; 
PSZ pszStartupDir; 
PSZ pszicon; 
PSZ pszEnvironment; 
SWP swpInitial; 
USHORT pad2[5]; 

} PROGDETAILS; 


/* progde */ 


The PROGDETAILS structure contains information about a program. 


Length Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


progt 


Specifies the PROGTYPE structure that contains program-type informa- 
tion. 
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pad1[3] Reserved. 


pszTitle Points to the null-terminated string that contains the program title. 
This string must not exceed MAXNAMEL (defined in the include files) charac- 
ters plus the terminating NOLL character. 


pszExecutable Points to the null-terminated string that contains the name of 
the executable file. If the string appears to be a fully qualified path (that is, it 
contains a colon in the second position and/or contains a backslash), the file is 
searched for in the indicated directory on the indicated drive. If neither of these 
conditions is true and the file is not in the current directory, each drive and 
directory specified in the path defined in the current program’s environment is 
searched. 


pszParameters Points to the null-terminated string that contains any parame- 
ters to pass to the program. 


pszStartupDir Points to the null-terminated string that contains the default 
drive and directory. 


pszIcon Points to the null-terminated string that contains the name of an icon 
file. This parameter is not used for MS OS/2, version 1.2. 


pszEnvironment Points to the string that contains the environment variables. 
Each string is null-terminated, with the final string ending with two NULL char- 
acters. 


swpInitial Specifies the SWP structure that contains the initial state of the 
program’s window. If the cy, ex, y, and x fields of this structure are zero, a 
default window size is used when the application is started. 


pad2[5]_ Reserved. 
See Also PrfAddProgram, PrfChangeProgram, PrfQueryDefinition, PROGTYPE, SWP 


PROGTITLE New 


typedef struct _PROGTITLE { /* progti */ 
HPROGRAM hprog; 
PROGTYPE progt; 
USHORT padi[3]; 


PSZ pszTitle; 
} PROGTITLE; 


The PROGTITLE structure is used to specify program-title information. 


Fields hprog Specifies the handle of the program. 
progt Specifies the PROGTYPE structure that contains program-type informa- 
tion. 


padi[3] Reserved. 
pszTitle Points to the string that contains the program title. 


See Also PrfQueryProgramTitles, PROGTYPE 
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I PROGTYPE —_ Change 


typedef struct _PROGTYPE { /* progt */ 
PROGCATEGORY progc; : 
BYTE fbVisible; 

} PROGTYPE; 


The PROGTYPE structure is used in the PIBSTRUCT and PROGDETAILS 
structures to specify a program or group type. 


Fields proge Specifies the program category. This field can be one of the following 
values: 

Value Meaning 
PROG_DEFAULT Default category. 
PROG_FULLSCREEN Program runs only in a full-screen session. 
PROG_WINDOWABLEVIO Program runs in a VIO-window session. 
PROG_PM Program is a Presentation Manager application. 
PROG_GROUP Handle is to a group. 
PROG_REAL Program is a (DOS) real-mode application. 
PROG_DLL Program is a dynamic-link library. 


fb Visible Specifies the visibility of a program and (optionally) the protected 
or unprotected state of a group. This flag can be a combination of the following 


values: 
Value Meaning 
SHE_VISIBLE The program or group is visible. 
SHE_IN VISIBLE The program or group is invisible and cannot be 
viewed. 
SHE_UNPROTECTED The group is unprotected. Programs can be 


added or deleted from the group. This value is 
valid only for groups. 


SHE_PROTECTED The group is protected. Programs cannot be 
added or deleted from the group; the only pro- 
gram information that can be changed is the visi- 
bility state. This value is valid only for groups. 


See Also PIBSTRUCT, PROGDETAILS 


Changes The fbVisible field has two additional options (SHE_UNPROTECTED and 
SHE_PROTECTED) that can be set when the structure is used to create or 
change a group. The program category PROG_DLL has also been added. 
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H PTRACEBUF Change 


typedef struct _PTRACEBUF { /* ptrebf */ 
PID pid; 
TID tid; 
USHORT cmd; 
USHORT value; 
USHORT offv; 
USHORT segv; 
USHORT mte; 
USHORT rAX; 
USHORT rBX; 
USHORT rCx; 
USHORT rDX; 
USHORT rSI; 
USHORT rDI; 
USHORT rBP; 
USHORT rDS; 
USHORT rES; 
USHORT rIP; 
USHORT rCS; 
USHORT rE; 
USHORT rSP; 
USHORT rSS; 
} PTRACEBUE; 


The PTRACEBUF structure contains various debugging information. 


Fields pid Specifies the process identifier of the program being debugged. 
tid Specifies the thread identifier of the program being debugged. 
cmd _ Specifies the command to carry out. It can be one of the following 


values: 

Value Meaning 

0x0001 Read memory instruction space (I-space). 

0x0002 Read memory data space (D-space). 

0x0003 Read registers. 

0x0004 Write memory I-space. 

0x0005 Write memory D-space. 

0x0006 Write registers. 

0x0007 Begin execution. 

0x0008 Terminate child process. 

0x0009 Single step. 

O0x000A Suspend child process. 

0x000B Freeze child process. 

0x000C Resume child process. 

0x000D Convert segment number to selector. 

0x000E Get floating-point registers. The segv and offv fields must 
specify the address of a 94-byte buffer that receives the 
floating-point register values. 

OxO000F Set floating-point registers. The segv and offv fields must 


specify the address of a 94-byte buffer that contains the 
floating-point register values. 
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Value 


0x0010 


0x0011 


Meaning 


Get library-module name. The value field must contain the 
handle of the library module. The segy and offv fields must 
contain the address of the buffer that receives the name. This 
command should be used instead of the DosGetModHandle 
and DosGetModName functions to verify the name of a library 
loaded by the program being debugged. 


Get the thread identifier of the next thread. This field is circu- 
lar; to read the registers of all threads in the process, use this 
value until a thread identifier is repeated. For more informa- 
tion about this value, see the “Comments” section. 


When the command identified in the emd field returns, it copies a code to the 
value field that specifies the result of the command. The return code can be one 
of the following values: 


Value 
0x0000 
OxFFFF 
OxFFFE 
OxFFFD 
OxFFFC 
‘ OxFFFB 
OxFFFA 
OxFFF9 


OxFFF8 


OxFFF7 
OxFFF6 
OxFFFS 


Meaning 


Success return code. 

Error. The error code is in the value field. 
About to receive signal. 

Single-step interrupt. 

Hit break point. 

Parity error. 

Process dying. 


General protection fault. The fault type is in the value field. 
The segv and offv fields contain the address that caused the 
fault. 


Library module has just been loaded. The value field contains 
the library-module handle. 


Process has not used 287 yet. 
Thread ending. 


Asynchronous stop. 


value Specifies the value to be used for a given command or a return value 
from a command. If an error occurs, this field is set to one of the following 


values: 
Value 


Meaning 


0x0001 
0x0002 
0x0005 


Bad command. 
Child process not found. 


Child process untraceable. 


offv Specifies the offset from the given segment. 


segv Specifics the segment selector. 
mte Identifies the handle of the module that contains the segment. 
rAX Specifies the ax register. 


rBX Specifies the bx register. | 
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rCX Specifies the ex register. 
rDX_ = Specifies the dx register. 
rSI Specifies the si register. 
rDI Specifies the di register. 
rBP Specifies the bp register. 
rDS__ Specifies the ds register. 
rES Specifies the es register. 
rIP Specifies the ip register. 
rCS__ Specifies the es register. 
rF Specifies flags. 
rSP Specifies the sp register. 
rSS__ Specifies the ss register. 
Comments The 0x0011 value in the cmd field causes a thread identifier to be retrieved. The 


status of this thread is returned in a ThreadStatus buffer pointed to by the segy 
and offv fields. The format of the ThreadStatus buffer i is as follows: 


struct ThreadStatus { 
UCHAR fDebugState; 
UCHAR fThreadState; 
USHORT usThreadPriority; 


}; 
The DebugState field contains one of the following values: 
- Value Meaning 
0x0 Thread not frozen by debugger. 
Ox1 Thread frozen by debugger. 
The ThreadState field contains one of the following: 
Value Meaning 
0x0 Thread can be run. 
0x1 Thread is suspended. 
Ox2 Thread is blocked. 
Ox3 Thread state is a critical section. 


The ThreadPriority field receives the priority of the specified thread. The high 
byte receives the priority class, and the low byte receives the priority level. 


See Also DosGetModHandle, DosGetModName, DosPTrace 


Changes An additional value, 0x0011, can be specified for the cmd field. Two additional 
values, OxFFF6 and OxFFF5, can be returned in the cmd field. 
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m™ PTRDRAWDATA New 


Fields 


See Also 


—H SBCDATA 


Fields 


Changes 


typedef struct _PTRDRAWDATA { /* ptrdd */ 
USHORT cb; 
USHORT usConfig; 
USHORT usFlag; 

} PTRDRAWDATA; 


The PTRDRAWDATA structure contains data for drawing the pointer. 
cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


usConfig Specifies the display configuration. It can be one of the following 
values: 


Value Meaning 
VIO_CONFIG_CURRENT _ The current display adapter 


VIO_CONFIG_PRIMARY _ The primary display adapter 
VIO_CONFIG_SECONDARYThe secondary display adapter 


usFlag Specifies a flag that determines if this configuration is for an applica- 
tion or the base video subsystem (BVS). A value of 0x0000 specifies an applica- 
tion; 0x0001 specifies the BVS. 


MOU_SETPROTDRAWADDRESS 


Change 


typedef struct _SBCDATA { /* sbed */ 
USHORT cb; . 
USHORT sHilite; 
SHORT posFirst; 
SHORT posLast; 
SHORT posThumb; 
SHORT cVisible; 
SHORT cTotal; 
} SBCDATA; 


The SBCDDATA structure contains information about a scroll-bar window. 


cb Specifies the size of the structure (in bytes). The size depends on the ver- 
sion of the operating system. Programs written in the C language should use the 
sizeof operator to set this field. 


SHilite reserved, should be set to zero 

posFirst Specifies the first possible position of the slider bar. 
posLast Specifies the last possible position of the slider bar. 
posThumb Specifies the current position of the slider bar. 


cVisible Specifies the number of items (lines in a file, rows on a spreadsheet, 
etc) that are visible in the window. 


cTotal Specifies the total number of items to be displayed. 


The fields cVisible and cTotal have been added. 


mM STATUSDATA 
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Correction 


Fields 


See Also 


Corrections 


m@ SWBLOCK 


typedef struct _STATUSDATA { /* stsdata */ 
USHORT Length; 
USHORT SelectInd; 
USHORT BondInd; 

} STATUSDATA; 


The STATUSDATA structure contains status information about a session. 


Length Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


SelectInd Specifies whether the target session should be set as selectable or 
nonselectable. It can be one of the following values: 


Value Meaning 
TARGET_UNCHANGED Leave current setting unchanged. 
TARGET_SELECTABLE Set as selectable. 


TARGET_NOT_SELECTABLE Set as nonselectable. 


BondInd Specifies which session to bring to the foreground the next time the 
parent session is selected. It can be one of the following values: 


Value Meaning 
BOND_UNCHANGED Leave current setting unchanged. 
BOND_CHILD A bond between the parent session and the 


child session is established. The child session is 
brought to the foreground the next time the 
parent session is selected. If the child session is 
selected, the child session is brought to the fore- 
ground. 


BOND_NONE Any bond previously established with the 
specified child session is broken. The parent ses- 
sion is brought to the foreground the next time 
the parent session is selected and the child ses- 
sion is brought to the foreground the next time 
the child session is selected. 


DosSetSession 


The third field is BondInd, not BindInd. Accordingly, the three constants have 
been changed to BOND_. 


New 


typedef struct _SWBLOCK { /* swhlk */ 
USHORT cswentry; 
SWENTRY aswentry[1]; 

} SWBLOCK; 


The SWBLOCK structure contains an array of SWENTRY structures that con- 
tain information about the programs in the Task List. 
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Fields 


See Also 


mM TRACKINFO 


cswentry Specifies the number of SWENTRY structures contained in the 
aswentry field. 


aswentry[1] Contains an array of SWENTRY structures. 


WinQuerySwitchList, SWENTRY 


Change 


Fields 


typedef struct _TRACKINFO { 
SHORT cxBorder; 
SHORT cyBorder; 
SHORT cxGrid; 
SHORT cyGrid; 
SHORT cxKeyboard; 
SHORT cyKeyboard; 
RECTL rclTrack; 
RECTL rclBoundary; 
POINTL ptlMinTrackSize; 
POINTL ptlMaxTrackSize; 
USHORT fs; 
USHORT cxLeft; 
USHORT cyBottom; 
USHORT cxRight; 
USHORT cyTop; 

} TRACKINEO; 


/* ti */ 


The TRACKINFO structure contains information about a tracking rectangle used 
by the WinTrackRect function. 

cxBorder Specifies the border width. 

cyBorder  Spccifies the border height. 

exGrid Specifies the horizontal bounds of the tracking movements. 

cyGrid Specifies the vertical bounds of the tracking movements. 


cxKeyboard Specifies the amount of horizontal movement that occurs when 
the user presses the left arrow key. 


cyKeyboard Specifies the amount of vertical movement that occurs when the 
user presses the left arrow key. 


rceilTrack Specifies the starting tracking rectangle. This is modified as the rect- 
angle is tracked and holds the new tracking position when tracking is complete. 


reclBoundary Specifies an absolute boundary for the tracking rectangle. 


ptIMinTrackSize Specifies the minimum tracking size. 


ptIMaxTrackSize Specifies the maximum tracking size. 
fs Specifies tracking options. This field can be a combination of the following 
values: 

Option Meaning 

TF_LEFT Track the left side of the rectangle. 

TF_TOP Track the top side of the rectangle. 

TF_RIGHT Track the right side of the rectangle. 

TF_BOTTOM Track the bottom side of the rectangle. 


See Also 
Changes 


Corrections 
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Option Meaning 


TF_MOVE Track all sides of the rectangle. 


TF_SETPOINTERPOS Repositions the pointer according to the other 
_ options specified. 


TF_LEFT Vertically centers the pointer at the left of the 
tracking rectangle. 


TF_TOP Horizontally centers the pointer at the top of the 
tracking rectangle. 

TF_RIGHT Vertically centers the pointer at the right of the 
tracking rectangle. 

TF_BOTTOM Horizontally centers the pointer at the bottom of 
the tracking rectangle. 

TF_MOVE Centers the pointer in the tracking rectangle. 

TF_GRID Restricts tracking to the grid defined by exGrid and 

cyGrid. 
TF_STANDARD The width, height, grid-width and grid-height are all 


multiples of border-width and border-height. 


TF_ALLINBOUNDARY Performs tracking so that no part of the tracking 
rectangle ever falls outside the bounding rectangle. 


TF_PARTINBOUNDARY Performs tracking so that values of cxLeft, cyBot- 
tom, cxRight, and cyTop specify how much of the 
corresponding edge of the tracking rectangle must 
be kept within the opposite edge of the boundary 
rectangle. 


exLeft Specifies how much of the tracking rectangle must be kept within the 
boundary rectangle. Used only if fs is TF_LPARTINBOUNDARY. 


cyBottom Specifies how much of the tracking rectangle must be kept within 
the boundary rectangle. Used only if fs is TF_LPARTINBOUNDARY. 


cxRight Specifies how much of the tracking rectangle must be kept within the 
boundary rectangle. Used only if fs is TF_LPARTINBOUNDARY. 


cyTop Specifies how much of the tracking rectangle must be kept within the 
boundary rectangle. Used only if fs is TF_PARTINBOUNDARY. 


WinTrackRect 
The TF_PARTINBOUNDARY option can be used in the fs field. . 


The TF_SETPOINTERPOS flag was incorrectly spelled TF_POINTERPOS. 


The TF_ALLINBOUNDARY flag was incorrectly spelled 
TF_ALINBOUNDARY. 
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mM VIOCOLORREG 


New 


Fields 


See Also 


typedef struct _VIOCOLORREG { /* viocreg */ 
USHORT cb; 
USHORT type; 
USHORT firstcolorreg; 
USHORT numcolorregs; 
PCH colorregaddr; 
} VIOCOLORREG; 


The VIOCOLORREG structure contains the addresses of color registers. 
cb = Specifies the length of the structure (in bytes). The length determines how 
many color registers are retrieved. 


type Specifies the request type. To retrieve the color registers, this field must 
be set to 0x0003. 


firstcolorreg Specifies the first color register to be retrieved. This field must 
be a value from 0x0000 through 0x000F. The color registers are in sequential 
order. The number of registers retrieved depends on the structure size, as 
specified by the cb field. 


numcolorregs Specifies the number of color registers to retrieve. 


colorregaddr Points to the array that receives the color values for the regis- 
ters. For each color-register retrieved, there should be three bytes allocated (one 
each for the red, green, and blue color values). 


VioGetState, VioSetState 


— VIOCONFIGINFO Change 


Fields 


typedef struct _VIOCONFIGINFO { /* vioin */ 
USHORT cb : 
USHORT adapter; 
USHORT display; 
ULONG cbMemory; 
USHORT Configuration; 
USHORT VDHVersion; 
USHORT Flags; 
ULONG HWBuf ferSize; 
ULONG FullSaveSize; 
ULONG PartSaveSize; 
USHORT EMAdaptersOFF; 
USHORT EMDisplaysOFF; 

} VIOCONFIGINEO; 


The VIOCONFIGINFO structure contains configuration information about the 
screen. 


cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


See Also 
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adapter Specifies the type of display adapter. It can be one of the following 
values: 


Value Meaning 

DISPLAY_MONOCHROME Monochrome/printer adapter 

DISPLAY_CGA Color graphics adapter 

DISPLAY_EGA Enhanced graphics adapter 

DISPLAY_VGA Video graphics array display adapter 

DISPLAY_8514A IBM Personal System/2 display adapter 
8514/A 


display Specifies the display/monitor type. It can be one of the following 
values: 


Value Meaning 
MONITOR_MONOCHROME Monochrome display 
MONITOR_COLOR Color display 
MONITOR_ENHANCED Enhanced color display 
MONITOR_8503 8503 monochrome display 
MONITOR_851X_COLOR 8512 or 8513 color display 
MONITOR_8514 8514 color display 


cbMemory Specifies the amount of memory in the adapter (in bytes). 


Configuration Specifies the configuration ID requested. It can be one of the 
following values: 


Value Meaning 
VIO_CONFIG_CURRENT The current display adapter 
VIO_CONFIG_PRIMARY The primary display adapter 


VIO_CONFIG_SECONDARY The secondary display adapter 


VDHVersion Reserved; must be zero. 
Flags Specifies flag bits. The value 0x0001 sets default power-on configuration. 


HWBufferSize Specifies the amount of memory required to save the full 
hardware state of the device adapter (not including the physical video buffer). 


FullSaveSize Specifies the amount of memory required to save the entire 
physical video buffer. 


PartSaveSize Specifics the amount of memory required to save the portion of 
the physical video buffer that will be overwritten by a pop-up window. 


EMAdaptersOFF  Spccifies the offset to information that describes other 
display adapters emulated by this display adapter. 


EMDisplaysOFF Specifies the offset to information that describes other 
display types emulated by this display. 


VioGetConfig 
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Changes The following fields have been added to the end of the VIOCONFIGINFO struc- 
ture: 


USHORT' Configuration; 

USHORT VDHVersion; 

USHORT Flags; 

ULONG HWBufferSize; 

ULONG FullSaveSize; ‘ 
ULONG PartSaveSize; 

USHORT EMAdaptersOFF; 

USHORT EMDisplaysOFEF; 


H VIOFONTCELLSIZE New 


typedef struct _VIOFONTCELLSIZE { /* viofesz */ 
LONG X%cox%; 
LONG %cy%; 

} VIOFONTCELLSIZE; 


The VIOFONTCELLSIZE structure specifies the size of a font cell. 


Fields cx Specifies the width of the font cell. 
cy Specifies the length of the font cell. 
See Also DevEscape 
—H VIOMODEINFO Change 
typedef struct _VIOMODEINFO { /* viomi */ 
USHORT cb; 


UCHAR fbType; 

UCHAR’ color; 

USHORT col; 

USHORT row; 

USHORT hres; 

USHORT vres; 

UCHAR fmt_ID; 

UCHAR attrib; 

ULONG buf_addr; 

ULONG buf_length; 

ULONG) full_length; 

ULONG partial_length; 

PCH ext_data_addr; 
} VIOMODEINEO; 


The VIOMODEINFO structure contains information about the screen mode. 


Fields cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


fbType Specifics the screen mode. It is one of the following values: 
Value Meaning 


VGMT_OTHER Set adapter to other than a monochrome/printer 
adapter. If this value is not given, the 
monochrome/printer adapter is assumed by 
default. 


See Also 
Changes 
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Value Meaning 

VGMT_GRAPHICS Set graphics mode. If this value is not given, the 
adapter is set to text mode. 

VGMT_DISABLEBURST Disable color-burst mode. If this value is not 


given, color-burst mode is enabled. 


color Specifies the number of colors (defined as a power of 2). This is 
equivalent to the number of color bits that define the color. It is one of the fol- 
lowing values: 


Value Meaning 


COLORS_2 2 colors 
COLORS_4 4 colors 
COLORS_16 16 colors 


col Specifies the number of text columns. 

row Specifies the number of text rows. 

hres Specifies the number of pel columns (horizontal resolution). 
vres Specifies the number of pel rows (vertical resolution). 
fmt_ID Specifies the format of the attributes. 

attrib Specifies the number of attributes in the attribfmt field. 


buf_addr Specifies the 32-bit physical address of the physical video buffer for 
this mode. 


buf_length Specifies the length (in bytes) of the physical video buffer for this 
mode. ' 


full_length Specifies the size (in bytes) of the buffer required to save the 
entire physical video buffer for this mode. 


partial_length Specifies the amount of memory required to save a portion of 
the physical video buffer for this mode. This portion of the physical video buffer 
is what is overwritten by a pop-up window. 


ext_data_addr Specifies the far address of an extended-mode data structure, 
or zero if there is none. 


VioGetMode, VioSetMode 


The following fields have been added to the end of the VIOMODEINFO struc- 
ture: 


UCHAR fmt_ID; 

UCHAR attrib; 

ULONG buf_addr; 
ULONG buf_length; 
ULONG) full_length; 
ULONG partial_length; 
PCH ext_data_addr; 
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VIOSETTARGET New 


typedef struct _VIOSETTARGET { /* viosett */ 
USHORT ch; 
USHORT type 
USHORT de Fauavelgoeithne 

} VIOSETTARGET; 


The VIOSETTARGET structure identifies the target display of the next call to 
the VioSetMode function. 


Fields cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


type Specifies the request type. To retrieve the target information, this field 
must be set to 0x0006. 


defaultalgorithm Specifies the target display of the next call to the VioSet- 
Mode function. A value of 0x0000 specifies the default display (the active display 
when the computer was powered on), 0x0001 specifies the primary display, and 
0x0002 specifies the secondary display. 


See Also VioGetState, VioSetMode, VioSetState 
VIOSETULINELOC New 
, typedef oo ~VIOSETULINELOC { /* viouline */ 
USHORT cb; 


USHORT type; 
USHORT scanline; 
} VIOSETULINELOC; 


The VIOSETULINELOC structure contains the location of the underline. 


Fields cb Specifies the size of the structure (in bytes). Programs written in the C 
language should use the sizeof operator to set this field. 


type Specifies the request type. To retrieve the underline location, this field 
must be set to 0x0005. 


scanline Specifies the location of the underline. This value is normally in the 
range 0 through - 1 (the value of the scan line minus 1). A value of 32 means 
that underlining is disabled. 


See Also VioGetState, VioSetState 


m@ VIOSIZECOUNT 


WNDPARAMS = 409 


New 


typedef struct _VIOSIZECOUNT { /* viosz */ 
LONG %MaxCount%; 
LONG %CountZ%; 

} VIOSIZECOUNT; 


The VIOSIZECOUNT structure contains the size of the VIOFONTCELLSIZE 
structure. 


Fields MaxCount Specifies the maximum number of occurrences of the 
VIOFONTCELLSIZE structure. 
Count Specifies the actual number of occurrences of the 
VIOFONTCELLSIZE structure. 
See Also DevEscape 
H WNDPARAMS Change 
typedef struct _WNDPARAMS { /* wprm */ 


Fields 


USHORT fsStatus; 
USHORT cchText; 

PSZ pszText; 
USHORT cbPresParams; 
PVOID pPresParams; 
USHORT cbCtlData; 
PVOID pCtlData; 

} WNDPARAMS ; 


The WNDPARAMS structure contains information about a window. 


fsStatus Specifies the window parameters which are to be set or queried. This 
can be any combination of the following values: 


Value Meaning 

WPM_TEXT Text 

WPM_CTLDATA Control data 
WPM_PRESPARAMS Presentation parameters 
WPM_CCHTEXT Size of text 
WPM_CBCTLDATA Size of control data 


WPM_CBPRESPARAMS | Size of presentation parameters 


cchText Specifies the length of the window text. 
pszText Points to the window text. 
cbPresParams Specifies the length of the presentation parameters. 


pPresParams Points to the PRESPARAMS structure that contains presenta- 
tion parameters. This field is NULL if there are no presentation parameters. 


cbCtlIData Specifies the length of the class-specific data. 
pCtIData Points to the class-specific data. 
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See Also PRESPARAMS, WM_QUERYWINDOWPARAMS, 


WM_SETWINDOWPARAMS 
Changes The following constants have been defined for the fsStatus field: 
Value Meaning 
WPM_TEXT Text 
WPM_CTLDATA Control data 
WPM_PRESPARAMS Presentation parameters 
WPM_CCHTEXT Size of text 
WPM_CBCTLDATA Size of control data 


WPM_CBPRESPARAMS _Size of presentation parameters 
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Bit masks, 7 
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C-language format, 5 
Calling conventions, 6 
CBM_HILITE, 42, 57 
CBMLISLISTSHOWING, 42, 57 
CBM_SHOWLIST, 42, 57 
CBN_EFCHANGE, 41, 42, 58 
CBN_EFCSCROLL, 42 
CBN_EFSCROLL, 58 
CBN_ENTER, 42, 58 
CBN_LBSCROLL, 42, 59 
CBN_LBSELECT, 41, 42 
CBN_LBSELECT, 59 
CBN .MEMERROR, 42, 59 
CBN _SHOWLIST, 42, 60 
CHARBUNDLE, 363 
Combination-box control, 40-42 
Combo box, 40-42 
messages sent from, 42 
messages sent to, 42 
Constant names, 11 
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DENAI, 364 

DevEscape, 60 

DevPostDeviceModes, 66 

DevQueryCaps, 68 

DOS-compatibility mode, filenames, 
20 


DosAllocHuge, 72 
DosAllocSeg, 74 
DosAllocShrSeg, 76 
DosChgFilePtr, 19 
DosCopy, 77 
DosCreateSem, 79 
DosCreateThread, 80 
DosDevIOCtl2, 81 
DosEditName, 21, 82 
DosEnterCritSec, 83 
DosEnumAttribute, 84 
DosExecPgm, 21 
DosExitCritSec, 85 


DosExitList, 86 
DosFileIO, 88 
DosFileLocks, 19 
DosFindFirst, 21, 23 
DosFindFirst2, 90 
DosFindNext, 23, 93 
DosFreeResource, 95 
DosFreeSeg, 95 
DosFSAttach, 19, 96 
DosFSCtl, 18, 97 
DosGetDBCSEv, 99 
DosGetModHandle, 100 
DosGetResource, 101 
DosGetResource2, 102 
DosGetVersion, 103 
DosLoadModule, 104 
DosMakePipe, 105 
DosMkDir2, 23, 106 
DosMonReg, 107 
DosOpen, 19, 108 
DosOpen2, 23, 113 
DosQFHandState, 117 
DosOQFileInfo, 23, 119 
DosQFSAttach, 121 
DosQNmPipelnfo, 123 
DosQNmPipeSemState, 
DosQPathInfo, 23, 124 
DosQSysInfo, 20 
DosRead, 19, 126 
DosReadAsync, 128 
DosReadQueue, 130 
DosReallocHuge, 131 
DosReallocSeg, 133 
DosSearchPath, 134 
DosSemClear, 135 
DosSemRequest, 136 
DosSetFileInfo, 137 
DosSetMaxFH, 139 
DosSetPathInfo, 139 
DosSetPrty, 141 
DosSetVec, 142 
DosShutdown, 143 
DosStartSession, 144 
DosSubAlloc, 145 
DosSubFree, 146 
DosWaitNmPipe, 146 
DosWrite, 19, 147 
DosWriteAsync, 148 
DosWriteQueue, 150 
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E 
EAOP, 365 
EM_QUERYREADONLY, 152 
EM_SETINSERTMODE, 152 
EM_SETREADONLY, 152 
EM_SETTEXTLIMIT, 153 
EN_CHANGE, 153 
EN_INSERTMODETOGGLE, 153 
EN_KILLFOCUS, 154 
EN_MEMERROR, 154 
EN_OVERFLOW, 154 
EN_SCROLL, 155 
EN_SETFOCUS, 155 
Entry field, multiple-line, 42-50 
ENTRYFDATA, 365 
Error, file-system, 21-22 
Extended attribute, 23-28 

data type, 24 

data-type field, 27 

naming, 23 


F 
Fikey, 32, 35 
FAT (file allocation table), 17-18 
FATTRS, 366 
FEA, 367 
FEALIST, 368 
Field names, 8 
File allocation table (FAT), 17-18 
File system See Installable file 
system 
File-system error, 21-22 
FILEFINDBUF2, 368 
Filename 
conventions, 20 
DOS-compatibility mode, 20 
metacharacter, 21 
FILESTATUS2, 369 
FIOLOCKCMD, 370 
FIOLOCKREC, 370 
FIOREADWRITE, 371 
FIOSEEKCMD, 371 
FIOUNLOCKCMD, 372 
FIOUNLOCKREC, 372 
FONTMETRICS, 373 
FSINFO, 377 
FSQBUFFER, 378 
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G 

GEA, 379 

GEALIST, 379 
GpiCallSegmentMatrix, 156 
GpiCreateLogFont, 158 
GpiDestroyPS, 160 
GpiGetData, 160 
GpiLoadFonts, 162 
GpiOutlinePath, 163 
GpiPlayMetaFile, 164 
GpiPolyLine, 167 
GpiQueryBitmapBits, 168 
GpiQueryCharDirection, 170 
GpiQueryCharStringPos, 171 
GpiQueryDefArcParams, 173 
GpiQueryDefAttrs, 173 
GpiQueryDefTag, 175 
GpiQueryDefViewingLimits, 176 
GpiQueryFontFileDescriptions, 176 
GpiQueryMetaFileBits, 177 
GpiResetPS, 178 
GpiRotate, 180 

GpiScale, 181 
GpiSetCharDirection, 182 
GpiSetDefArcParams, 183 
GpiSetDefAttrs, 184 
GpiSetDefTag, 186 
GpiSetDefViewingLimits, 186 
GpiSetPS, 187 
GpiSetViewingLimits, 189 
GpiTranslate, 190 
GpiUnloadFonts, 191 
GpiWCBitBlt, 192 


H. 
HCINFO, 380 
Help 

button, 32, 37 

hook, 38 

instance, 33, 37 

library, 35 

menu, 32, 25 

table, 34 
Help Manager, 31-40 

messages sent by, 39 

messages sent to, 39-40 
HELPINIT, 33, 380 
HELPTABLE, 34, 381 
High-performance file system 

(HPFS), 17-18 
HM_ACTIONBAR_COMMAND, 
195 

HM_CREATE_HELP_TABLE, 195 
HM_DISMISS_WINDOW, 196 


HM_DISPLAY_HELP, 37, 196 

HM_ERROR, 32, 197 

HM_EXT_HELP, 37, 198 

HM_EXT_HELP_UNDEFINED, 
199 . 


- HM_HELP_CONTENTS, 199 


HM_HELP_INDEX, 37, 199 
HM_HELPSUBITEM_NOT_FOUND, 
200 
HM_INFORM, 201 
HM_KEYS_HELP, 37, 201 
HM_LOAD_HELP_TABLE, 202 
HM_QUERY_KEYS_HELP, 202 
HM_REPLACE_HELP_FOR_HELP, 
202 
HM_SET_ACTIVE_WINDOW, 34, 
203 
HM_SET_HELP_LIBRARY_NAME, 
203 
HM_SET_HELP_WINDOW_LITITLE, 
204 
HM_SET_SHOW_PANEL_ID, 204 
HM_TUTORIAL, 205 
HPFS (high-performance file 
system), 17-18 


l 

Include files, 5 

Information Presentation Facility 
Compiler (IPFC), 32 

Initialization file, 28-31 

Installable file system, 17-23 

IPFC (Information Presentation 
Facility Compiler), 32 


K . 
KbdCharIn, 205 
KbdGetHWID, 207 
KBDHWID, 382 
KBDKEYINFO, 383 
KbdRegister, 208 


L 

LDTADDRINFO, 384 
LINFOSEG, 384 
LM_INSERTITEM, 41 
Local file system, 19 


M 
MATRIXLF, 386 
MLE_SEARCHDATA, 387 


MLECTLDATA, 388 
MLEFORMATRECT, 390 
MLEMARGSTRUCT, 390 
MLEOVERFLOW, 391 
MLM_CHARFROMLINE, 48, 210 
MLM_CLEAR, 43, 45, 48, 211 
MLM_COPY, 45, 48, 211 
MLM_CUT, 45, 48, 212 
MLM_DELETE, 44, 48, 212 
MLM_DISABLEREFRESH, 45, 
48, 212 
MLM_ENABLEREFRESH, 45, 48, 
213 
MLM_EXPORT, 44, 48, 213 
MLM_FORMAT, 45, 48, 214 
MLM_IMPORT, 44, 48, 214 
MLM_INSERT, 43, 48, 215 
MLM_LINEFROMCHAR, 48, 215 
MLM_PASTE, 45, 48, 216 
MLM_QUERYBACKCOLOR, 44, 
48, 216 
MLM_QUERYCHANGED, 46, 48, 
217 
MLM_QUERYFIRSTCHAR, 46, 
48, 217 
MLM_QUERYFONT, 44, 48, 218 


MLM_QUERYFORMATLINELENGTH, 


45, 48, 218 
MLM_QUERYFORMATRECT, 
44, 48, 219 


MLM_QUERYFORMATTEXTLENGTH, 


45, 48, 220 
MLM_QUERYIMPORTEXPORT, 
48, 221 
MLM_QUERYLINECOUNT, 44, 
48, 221 
MLM_QUERYLINELENGTH, 48, 
2 
MLM_QUERYREADONLY, 44, 
48, 222 
MLM_QUERYSEL, 43, 49, 222 
MLM_QUERYSELTEXT, 45, 49, 
223 
MLM_QUERYTABSTOP, 44, 49, 
224 
MLM_QUERYTEXTCOLOR, 44, 
49, 224 
MLM_QUERYTEXTLENGTH, 44, 
49, 225 
MLM_QUERYTEXTLIMIT, 44, 
49, 225 
MLM_QUERYUNDO, 43, 49, 226 
MLM_QUERYWRAP, 44, 49, 226 
MLM_RESETUNDO, 43, 49, 227 
MLM_SEARCH, 46, 49, 227 
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MLM_SETBACKCOLOR, 44, 49, 
228 
MLM_SETCHANGED, 46, 49, 229 
MLM_SETFIRSTCHAR, 46, 49, 
229 
MLM_SETFONT, 44, 49, 230 
MLM_SETFORMATRECT, 44, 49, 
230 
MLM_SETIMPORTEXPORT, 44, 
49, 232 
MLM_SETREADONLY, 44, 49, 
232 
MLM_SETSEL, 43, 49, 233 
MLM_SETTABSTOP, 44, 49, 233 
MLM_SETTEXTCOLOR, 44, 49, 
234 
MLM_SETTEXTLIMIT, 44, 49, 
234 
MLM_SETWRAP, 49, 235 
MLM_UNDO, 43, 49, 235 
MLN_CHANGE, 46, 49, 236 
MLN_CLPBDFAIL, 49, 236 
MLN_HSCROLL, 46, 50, 237 
MLN_KILLFOCUS, 50, 237 
MLN_MARGIN, 50, 238 
MLN_MEMERROR, 50, 238 
MLN_OVERFLOW, 50, 238 
MLN_PIXHORZOVERFLOW, 50, 
239 
MLN_PIXVERTOVERFLOW, 50, 
240 
MLN_SEARCHPAUSE, 50, 240 
MLN_SETFOCUS, 50, 241 
MLN. TEXTOVERFLOW, 50, 241 
MLN_UNDOOVERFLOW, 50, 241 
MLN_VSCROLL, 46, 50, 242 
MM_DISMISSMENU, 242 
MM.QUERYSELITEMID, 242 
MOU_DISPLA YMODECHANGE, 
243 
MOU_SETPROTDRAWADDRESS, 
243 


MOU_SETREALDRAWADDRESS, ~ 


244 
MOU_UPDATEDISPLAYMODE, 
245 
MOUL_VER, 246 
MouGetNumQueEl, 247 
MouSynch, 248 
Multiple-line entry field (MLE), 
42-50 
copying text, 45 
editing text, 43 
exporting text, 44 
formatting text, 44 


Multiple-line entry field (MLE) (con- 
tinued) 
importing text, 44 
messages sent from, 49 
messages sent to, 48 
notification code, 46 
pasting text, 45 
searching and replacing text, 46 


N 


Naming conventions, 8-10 
Notational conventions, 11 


O 

Overviews, 13-50 
P 

PARAM, 392 


Parameter names, 8 
PicIchg, 249 

PicPrint, 250 
PIPESEMSTATE, 393 
PL_ALTERED, 250 
Prefixes, 9 
PRESPARAMS, 393 
PrfAddProgram, 29, 30, 250 
PrfChangeProgram, 252 
PrfCloseProfile, 29,253 | 
PrfCreateGroup, 29, 30, 253 
PrfDestroyGroup, 254 
PrfOpenProfile, 29, 255 
PRFPROFILE, 394 
PrfQueryDefinition, 255 
PrfQueryProfile, 30, 257 
PrfQueryProfileData, 29, 258 
PrfQueryProfileInt, 30, 259 
PrfQueryProfileSize, 29, 260 
PrfQueryProfileString, 29, 30, 261 
PrfQueryProgramCategory, 262 
PrfQueryProgramHandle, 263 
PrfQueryProgramTitles, 264 
PrfRemoveProgram, 265 
PrfReset, 30, 265 
PrfWriteProfileData, 266 
PrfWriteProfileString, 29, 267 
Profile Manager, 28-31 
PROGDETAILS, 394 
PROGTITLE, 395 
PROGTYPE, 396 
Pseudo-character device, 19 
PTRACEBUF, 397 
PTRDRAWDATA, 400 


R 


' Remote file system, 19 


S 

SBCDATA, 400 
SBM_SETTHUMBSIZE, 268 
SCRLALLOCLDT, 269 


‘SCR_ALLOCLDTOFF, 269 


SCR_DEALLOCLDT, 270 
Single-file device, 19 
STATUSDATA, 401 
Structures, 8, 361, 363-410 
SWBLOCK, 401 


T 

TBM_TRACKMOVE, 271 
TRACKINFO, 402 
Types, 8-10, 361, 362 


V 

VIOCOLORREG, 404 
VIOCONFIGINFO, 404 
VioCreatePS, 272 
VIOFONTCELLSIZE, 406 
VioGetBuf, 273 
VioGetConfig, 274 
VioGetMode, 275 
VioGetState, 276 
VIOMODEINFO, 406 
VioReadCellStr, 277 
VioScrollDn, . 278 
VioScrollLf, 280 
VioScrollRt, 281 
VioScrollUp, 282 
VioSetCurType, 283 
VioSetMode, 284 
VioSetState, 286 
VIOSETTARGET, 408 
VIOSETULINELOC, 408 
VioShowBuf, 287 . 
VIOSIZECOUNT, 409 
VioWrtCellStr, 288 
VioWrtNCell, 289 


W 

WinAddProgram, 290 

WinAssociateHelpInstance, 33, 38, 
291 \ 

WinBroadcastMsg, 292 

WinCreateFrameControls, 293 

WinCreateGroup, 293 
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WinCreateHelpInstance, 33, 294 
WinCreateHelpTable, 295 
WinCreatePointerIndirect, 296 
WinCreateSwitchEntry, 296 
WinCreateWindow, 41, 42, 47, 298 
WinDefDlgProc, 33 
WinDefWindowProc, 33 
WinDeleteLibrary, 300 
WinDeleteProcedure, 300 
WinDestroyHelpInstance, 38, 300 
WinDlgBox, 37 
WinDrawBitmap, 301 
WinEnumDlgItem, 302 
WinGetDlgMsg, 303 
WinGetLastError, 38. 
WinGetNextWindow, 304 
WinGetSysBitmap, 304 
WinInitialize, 29, 33 
WinInstStartApp, 306 
WinIsWindowShowing, 307 
WinLoadHelpTable, 308 
WinLoadLibrary, 308 
WinLoadProcedure; 309 
WinLockWindow, 309 
WinQueryActiveWindow, 309 
WinQueryAnchorBlock, 310 
WinQueryCapture, 310 


WinQueryClipbrdOwner, 310 
WinQueryClipbrdViewer, 311 
WinQueryDefinition, 311 
WinQueryFocus, 312 
WinQueryHelpInstance, 33, 313 
WinQueryPresParam, 313 
WinQueryProfileData, 315 
WinQueryProfileInt, 316 
WinQueryProfileSize, 317 
WinQueryProfileString, 318 
WinQueryProgramTitles, 318 
WinQuerySessionTitle, 320 
WinQuerySwitchEntry, 320 
WinQuerySwitchHandle, 321 
WinQuerySwitchList, 322 
WinQuerySysModalWindow, 322 
WinQuerySysValue, 323 
WinQueryTaskSizePos, 326 
WinQueryWindow, 327 
WinQueryWindowLockCount, 328 
WinRegisterClass, 328 
WinReleasePS, 330 
WinRemovePresParam, 331 
WinSetPresParam, 332 
WinSetSysColors, 333 
WinSetSysValue, 336 
WinSetWindowPos, 339 


WinSwitchToProgram, 342 
WinTerminateApp, 343 
WinWindowFromID, 343 
WinWindowFromPoint, 344 
WinWriteProfileData, 345 
WinWriteProfileString, 346 
WM_ADJUSTWINDOWPOS, 347 
WM_APPTERMINATENOTIFY, 
348 
WM_CALCFRAMERECT, 348 
WM_CALCVALIDRECTS, 349 
WM_CHAR, 350 
WM_CLOSE, 352 
WM_COMMAND, 36 
WM_CONTROL, 42 
WM_DRAWITEM, 352 
WM_FORMATFRAME, 353 
WM_MEASUREITEM, 354 
WM_MOVE, 355 
WM_PRESPARAMCHANGED, 
355 
WM_QUERYHELPINFO, 356 
WM_SAVEAPPLICATION, 357 
WML_SETHELPINFO, 357 
WM_WINDOWPOSCHANGED, 
358 
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Invest in CD-ROM Technology! 


Microsoft® Programmer's Library is the ultimate programmer's reference on a single CD-ROM. 
disc. It contains full text of the OS/2 Software Development Kit (SDK) manuals, the Windows 
SDK manuals, most Microsoft Language manuals, and several Microsoft Press books written 
for the serious programmer, including THE MS-DOS ENCYCLOPEDIA. Plus 20 floppies’ 
worth of "clip art" sample code. Navigate through this mass of programming knowledge with 
boolean searches and hypertextual links between related data. The price is $395 suggested 
retail— a fraction of the price for this material in print form. 


For a limited time, Programmer's Library is available System Complete with the Denon DRD- 
253 CD-ROM drive for $949. That's a savings of $575! 


And if you order now, you'll receive FREE Microsoft Audio Software ($99 value) that turns 
your CD-ROM drive into a programmable CD audio player. So you can Jisten to a keyboard for 
a change. 


Call (800) 227-4679 for details. 


For a Free Demo Disk* please 
Print your name and address: 


NAME 
COMPANY NAME (if applicable) 

STREET ADDRESS 

CITY STATE ZIP 


DAYTIME TELEPHONE (in case we have questions about your order) 


Check the appropriate box 


[_] 1.2 MB floppy Demo Disk: Contains the self-running demo as well as self-guided 
and interactive demos of the features of Programmer's Library. Also includes a 
portion of the actual Programmer's Library database. 


[_] 1.44 MB floppy Demo Disk: Same as above for 3.5 inch drives. 


[_] 360K floppy Demo Disk: The self-running demo showing the impressive features 
of Programmer's Library. 
Send this coupon to: 
Microsoft Corporation = Attn: Special Promotions, Dept 127 
16011 NE 36th Way = Box 97017 = Redmond, WA 98073-9717 


*Offer Valid While Supplies Last 


Step up to 
Presentation Manager with 
the Microsoft OS/2 


~ Presentation Manager 
Softset. 


Congratulations on your purchase of the Microsofts OS/2 Programmer’s Reference Library, 
a complete guide to the features of the Microsoft OS/2 Presentation Manager. Now that 
you have the documentation, the next step is to purchase Microsoft OS/2 Presentation 
Manager Softset version 1.1, which Microsoft designed to help software developers create 
the new generation of graphically based, intuitive, easy-to-use software applications. 
Softset provides a complete, fully documented set of visual software tools to help you 
create popular applications for the graphical environment of Presentation Manager. 
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¢ Dialog Editor helps you design on-screen dialog boxes. 

¢ Icon Editor helps you customize icons, cursors, and bitmap images for graphical 
applications. 

¢ Font Editor helps you create your own fonts. 

¢ Resource Compiler helps you bind resource-definition files created with the Dialog, 
Icon, and Font Editors to .EXE files. 

¢ Other Softset tools help you create and maintain libraries, create message files and 
dual-mode (DOS-OS/2) programs, and perform many other tasks. 


Combine the Softset with the Microsoft OS/2 Programmer’s Reference Library and a 
programming language such as Microsoft C Optimizing Compiler or Microsoft Macro 
Assembler with OS/2 support for a complete Presentation Manager software development 
kit. The applications you create in Presentation Manager are fully compatible with IBM: 
SAA (Systems Application Architecture). Trust the software tools from Microsoft— the 
company that developed MS. OS/2. 


Contact your nearest local software dealer for more information. 


Also Available From Microsoft’ Press 
Authoritative Information for OS/2 Programmers 


INSIDE OS/2 
Gordon Letwin, Chief Architect, Systems Software, Microsoft 
Foreword by Bill Gates 


‘*The best way to understand the overall philosophy of OS/2 will be to read this book.’’ 
— Bill Gates 


Here — from Microsoft’s Chief Architect of Systems Software — is an exciting 
technical examination of the philosophy, key development issues, programming im- 
plications, and role of OS/2 systems in the office of the future. And Letwin provides 
the first in-depth look at each of OS/2’s design elements. This is a valuable and 
revealing programmer-to-programmer discussion of the graphical user interface, 
multitasking, memory management, protection, encapsulation, interprocess commu- 
nication, and direct device access. You can’t get a more inside view. 


304 pages, 7% x 9%, softcover, $19.95 ISBN 1-55615-117-9 


ADVANCED OS/2 PROGRAMMING 


Ray Duncan 

Authoritative information, expert advice, and great programming examples make 
this comprehensive overview of the features and structure of OS/2 indispensable to 
any serious OS/2 programmer. Duncan addresses a range of significant OS/2 issues: 
programming the user interface; mass storage; memory management; multitasking; 
interprocess communications; customizing filters, device drivers, and monitors; and 
using OS/2 dynamic link libraries. A valuable reference section includes detailed 
information on each of the more than 250 system service calls in version 1.1 of the 

- OS/2 kernel. 


800 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-045-8 


PROGRAMMING THE OS/2 PRESENTATION MANAGER 
Charles Petzold 


Here is the first full discussion of the features and operation of the OS/2 1.1 Pres- 

- entation Manager. If you’re developing OS/2 applications, this book will guide you 
through Presentation Manager’s system of windows, messages, and function calls. 
Petzold includes scores of valuable C programs and utilities. Endorsed by the 
Microsoft Systems Software group, this book is unparalleled for its clarity, detail, 
and comprehensiveness. Petzold covers managing windows m handling input and 
output m controlling child windows @ using bitmaps, icons, pointers, and strings & 
accessing the menu and keyboard accelerators m working with dialog boxes m 
understanding dynamic linking m and more. 


864 pages, 7% x 9%, softcover, $29.95 ISBN 1-55615-170-5 


ESSENTIAL OS/2 FUNCTIONS: Programmer’s Se Reference 


Ray Duncan 

Concise information on the essential OS/2 function calls within the application pro- 
gram interface (API). Entries are included for all kernel API functions for OS/2 ver- 
sion 1.0: Dos, Kbd, Mou, and Vio. The book describes each function and provides a 
list of the required parameters, returned results, programming notes and warnings, 
family API call identification, and error codes. Conveniently arranged to provide 
quick access to the information you need. 

208 pages, 4% x 8, softcover, $9.95 ISBN 1-55615-177-2 


For the Windows” Programmer 


PROGRAMMING WINDOWS” 
Charles Petzold 


Your fastest route to successful application programming with Windows. Full of 
indispensable reference data, tested programming advice, and page after page of 
creative sample programs and utilities. Topics include getting the most out of the 
keyboard, mouse, and timer; working with icons, cursors, bitmaps, and strings; ex- 
ploiting Windows’ memory management; creating menus; taking advantage of child 
window controls; incorporating keyboard accelerators; using dynamically linkable li- 
braries; and mastering the Graphics Device Interface (GDI). A thorough, up-to-date, 
and authoritative look at Windows’ rich graphical environment. 


864 pages, 7% x 9¥%, softcover, $24.95 ISBN 0-914845-91-8 


Solid Technical Information for MS-DOS* Programmers 
ADVANCED MS-DOS’ PROGRAMMING, 2nd ed. 


Ray Duncan 

The preeminent source of MS-DOS information for assembly-language and C 
programmers — now completely updated with new data and programming advice 
covering ROM BIOS for the IBM PC, PC/AT, PS/2, and related peripherals; MS- 
DOS through version 4; version 4.0 of the LIM EMS; and OS/2 compatibility con- 
siderations. Duncan addresses key topics, including character devices, mass storage, 
memory allocation and management, and process management. In addition, there is a 
healthy assortment of updated assembly-language and C listings that range from code 
fragments to complete utilities. And the reference section, detailing each MS-DOS 
function and interrupt, is virtually a book within a book. 

688 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-157-8 


THE MS-DOS° ENCYCLOPEDIA 


Microsoft Press 

General Editor, Ray Duncan 

Foreword by Bill Gates 

The ultimate reference for insight, data, and advice to make your MS-DOS programs 
reliable, robust, and efficient. 1600 pages packed with version-specific data. Annota- 
tions of more than 100 system function calls, 90 user commands, and a host of key 
programming utilities. Hundreds of hands-on examples, thousands of lines of code, 
and handy indexes. Plus articles on debugging, writing filters, installable device 
drivers, TSRs, Windows, memory management, the future of MS-DOS, and much 
more. Researched and written by a team of MS-DOS experts — many involved in the 
creation and development of MS-DOS. Covers MS-DOS through version 3.2, with a 
special section on version 3.3. 

1600 pages, 7% x 10, softcover, $69.95 ISBN 1-55615-174-8 


Programmer’s Quick Reference Series 
MS-DOS’ FUNCTIONS 


Ray Duncan 

The kind of information every seasoned programmer needs right at hand. Includes 
detailed information on MS-DOS system service calls along with valuable program- 
ming notes. Covers MS-DOS through version 4. 

128 pages, 4% x 8, softcover, $5.95 ISBN 1-55615-128-4 


IBM”° ROM BIOS 


Ray Duncan 

Essential for every assembly-language or C programmer at any experience level. 
Designed for quick and easy access to information, this guide includes all the core 
information on each of the ROM BIOS services. 

128 pages, 4% x 8, softcover, $5.95 ISBN 1-55615-135-7 


MS-DOS” EXTENSIONS 


Ray Duncan 

Brings together the hard-to-find programming information on the Lotus/Intel/ 
Microsoft Expanded Memory Specification (EMS) version 4.0, the Lotus/Intel/ 
Microsoft/AST Extended Memory Specification (XMS) version 2.0, the Microsoft 
-CD-ROM Extensions version 2.1, and the Microsoft Mouse driver, version 6. An 
overview of each function is accompanied by a list of its required parameters, 
returned results, and applicable programming notes. 


128 pages, 4% x 8, softcover, $6.95 ISBN 1-55615-212-4 


Solid Language References 
MICROSOFT” C: SECRETS, SHORTCUTS & SOLUTIONS 


Kris Jamsa 

Here is a fact-filled, example-packed resource for any current or aspiring Microsoft 
C programmer working in the DOS environment. Each chapter highlights specific C 
programming facts, tips, and traps so that key information or items of special interest 
are immediately accessible. Hundreds of short sample programs support Jamsa’s in- 
struction and encourage experimentation. If you’re new to C, Microsoft C, or even 
Microsoft QuickC, Jamsa’s fast-paced, highly readable style will help you quickly 
master the fundamentals. If you’re a seasoned programmer, you’ll find page after 
page of advanced information that will hone your programming skills and make your 
Microsoft C programs fast, clean, and efficient. Jamsa shows you how to m access the 
DOS command line m expand wildcard characters into matching filenames ™ use I/O 
redirection m master dynamic memory allocation m take advantage of C’s predefined 
global variables m optimize your programs for increased speed m enhance your pro- 
gram’s video appearance m make full use of the MAKE and LIB tools. 


736 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-203-5 


PROFICIENT C 


Augie Hansen 


“A beautifully-conceived text, clearly written and logically organized...a superb guide.” 
Computer Book Review 


An information-packed handbook for intermediate to advanced DOS programmers 
that includes dozens of file-oriented and screen-oriented C programs and specially 
developed utilities. A successful blend of programming advice and practical example 
programs. 


512 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-007-5 


VARIATIONS IN C, 2nd ed. 


Steve Schustack 

Foreword by Gerald Weinberg 

A superb guide for experienced programmers who want to develop efficient, portable, 
high-quality application software using C in the DOS environment. In addition to an 
overview of the basic syntax of C, Schustack provides valuable techniques for struc- 
tured programming. A complete, 1500-line sample order entry program illustrates 
key topics. Special comments and cautions are highlighted throughout. 

448 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-239-6 


STANDARD C: Programmer’s Quick Reference 
P.J. Plauger and Jim Brodie 


All the basic information you need to read and write Standard C programs that 
conform to the recently approved ANSI and ISO standard for the C programming 
language. Scores of diagrams illustrate the syntax rules. Whether you’re new to C or 
familiar with an earlier dialect, this will prove a handy companion. 

224 pages, 4% x 8, softcover, $7.95 ISBN 1-55615-158-6 


THE WAITE GROUP’S MICROSOFT® QUICKC” 
PROGRAMMING, 2nd ed. 


The Waite Group: Mitchell Waite, Stephen Prata, Bryan Costales, 

Harry Henderson 

This second edition has been completely updated to cover the latest version of 
Microsoft QuickC, including information on the new in-line macro assembler. The 
Waite Group provides a comprehensive survey of the C language and details on the 
many unique capabilities of QuickC. They have packed the book with advice, tips, 
and scores of specially constructed listings. Also included are special notes for pro- 
grammers with experience in another language such as BASIC or Pascal. 


650 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-258-2 


MICROSOFT® QUICKC® PROGRAMMER’S TOOLBOX 

An Essential Library of More Than 250 Programs, Functions, and Utilities 
for Supercharging QuickC Programs 

John Clark Craig 


This will be a valuable resource for both novice and seasoned Microsoft QuickC pro- 
grammers. The more than 250 programs and functions reinforce effective modular 
programming techniques while solving common and unusual programming prob- 
lems. Each program and function takes maximum advantage of QuickC’s capabilities 
and can be used with any version of the software. Programs address mouse support, 
editing and formatting routines, QuickC’s graphics functions, menu customization, 
random and complex numbers, and more. 


500 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-207-8 


THE MICROSOFT® QUICKBASIC PROGRAMMER’S TOOLBOX | 
John Clark Craig 


This essential library of subprograms, functions, and utilities developed to super- 
charge your QuickBASIC programs—addresses common and unusual programming 
tasks: ANSI.SYS screen control @ mouse support ™ pop-up windows @ graphics @ 
string manipulations m bit manipulation m editing routines H game programming @ 
interlanguage calling m and more. Each program takes maximum advantage of 
QuickBASIC’s capabilities. You’re guaranteed to turn to this superb collection again 
and again. — 

512 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-127-6 


MICROSOFT® QUICKBASICS 3rd ed. 
Douglas Hergert | 


“*No matter what your level of programming experience, you'll find this book 
irreplaceable when you start to program in QuickBASIC.’’ Online Today 


If you’re an intermediate-level BASIC, Pascal, or C programmer ready to make the 
transition to a professional programming environment, MICROSOFT QUICKBASIC 
is an excellent introduction to structured programming and a superb guide to writing 
long, useful programs. Included are six full-length programs that highlight data types 
and data structures, decision and looping structures, sequential data files, the power- 
ful graphics commands, and event trapping. Hergert has updated the book to address 
the new QuickBASIC user-interface enhancements of version 4.5. 


400 pages, 7% x 9%, softcover, $21.95 ISBN 1-55615-236-1 


Unbeatable Programmer’s References 


PROGRAMMER’S GUIDE TO PC & PS/2° VIDEO SYSTEMS 
Richard Wilton 


No matter what your hardware configuration, here is all the information you need 
to create fast, professional, even stunning video graphics on IBM PCs, compatibles, 
and PS/2s. No other book offers such detailed, specialized programming data, 
techniques, and advice to help you tackle the exacting challenges of programming 
directly to the video hardware. And no other book offers the scores of invaluable 
source code examples included here. Whatever graphic output you want — text, 
circles, region fill, bit blocks, animation— you’ll achieve it more cleanly, quickly, 
and effectively with Wilton’s book. 

544 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-103-9 


THE 80386 BOOK 
Ross P. Nelson 


A clear, comprehensive, and authoritative introduction for every serious programmer. 
Included are scores of superb assembly-language examples along with a detailed 
analysis of the 80386 chip. Topics include the CPU, the memory architecture, the in- 
struction sets of the 80386 microprocessor and the 80387 math coprocessor, the pro- 
tection scheme, the implementation of a virtual memory system through paging, and 
compatibility with earlier Intel microprocessors. Of special note is the comprehen- 
sive, clearly organized instruction set reference — guaranteed to be a valuable 
resource. 


464 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-138-1 


THE PROGRAMMER’S PC SOURCEBOOK 
Thom Hogan 


At last! A reference to save you the time required to find key pieces of technical 
data. Here is important factual information — previously published in scores of other 
sources — organized into one convenient reference. Focusing on IBM PCs and com- 
patibles, PS/2s, and MS-DOS, the hundreds of charts and tables cover 

m@ numeric conversions and character sets # DOS commands and utilities m 

DOS function calls and support tables m DOS BIOS calls and support tables m other 
interrupts, mouse, and EMS support m Microsoft Windows m keyboards, video 
adapters, and peripherals m chips, jumpers, switches, and registers m hardware de- 
scriptions m and more. 


560 pages, 8% x 11, softcover, $24.95 ISBN 1-55615-118-7 


THE NEW PETER NORTON PROGRAMMER’S GUIDE 
TO THE IBM? PC & PS/2° 


Peter Norton and Richard Wilton 

A must-have classic on mastering the inner workings of IBM micros — now com- 
pletely updated to include the PS/2 line. Sharpen your programming skills and learn 
to create simple, clean, portable programs with this successful combination of astute 
programming advice, proven techniques, and solid technical data. Covers 8088, 
80286 and 80386 microprocessors; ROM BIOS basics and ROM BIOS services; 
video, disk, and keyboard basics; DOS basics, interrupts, and functions (through ver- 
sion 4); and interrupts, device drivers, and video programming. Accept no substi- 
tutes; this is the book to have. 

528 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-131-4 


The Microsoft® Press CD-ROM Library 
THE MICROSOFT” CD-ROM YEARBOOK 1989-1990 


Microsoft Press 

Foreword by Bill Gates 

A dynamic, fact-filled portrait and analysis of the wide-ranging, fast-paced CD-ROM 
industry. Indispensable for anyone involved in the industry as well as an information- 
packed compendium for those curious about CD-ROM. Readers can use the book as a 
valuable sourcebook of facts, statistics, and forecasts or dip into it for fascinating ar- 
ticles, reviews, and analyses of the industry. Articles include: 


@ an absorbing history —in text and pictures — of the CD-ROM industry 

m™ reviews of products —hardware and software — considered outstanding or 
standard-setting 

m profiles of the leading companies and people in the industry 

m an overview of the process of developing a CD-ROM product 

m@ areview of the legal issues of piptecion: rights and Eons contracts, and 
royalties 

m the strategies and pitfalls involved in getting a CD- ROM product to market 


The breadth of accurate, up-to-date information in THE MICROSOFT 
CD-ROM YEARBOOK is impressive, including: 


m= comprehensive reference listings of the people, equipment, available titles, 
sources, and resources in the CD-ROM industry 

m a glossary of industry terms 

m™ acalendar of industry events and conferences | 

m@ specialized bibliographies 

This is the reference for fact and opinion on the CD-ROM industry. 

960 pages, 8% x 11, softcover, $79.95 ISBN 1-55615-179-9 


CD-ROM 2: OPTICAL PUBLISHING 
Edited by Suzanne Ropiequet with John Einberger and Bill Zoellick 


**Recommended reading for any information professional.’’ Online Today 


A comprehensive overview of the entire optical publishing process. Topics include 
evaluating and defining storage and retrieval methods; collecting, preparing, and in- 
dexing data; updating strategies; data protection and copyrighting; and more. Plus 
information on the High Sierra Logical Format. In addition, the editors trace the 
development of two CD-ROM projects from initial concept to final product. For 
publishers, technical managers, and entrepreneurs. 


368 pages, 7% x 9%, softcover, $22.95 ISBN 1-55615-000-8 


INTERACTIVE MULTIMEDIA 


Foreword by John Sculley | 

Edited by Sueann Ambron and Kristina Hooper 

Apple Computer brought together leading researchers and developers to produce this 
informative collection of 21 articles. The result is a sourcebook of ideas and inspira- 
tion for software and hardware developers, educators, publishers, and information 
providers. The contributors, including Doug Englebart, Sam Gibbon, and Peter Cook, 
represent the industries — computers, television, and publishing — whose products 
will provide the content and media for education in the future. Filled with examples 
and pilot projects that define the new meaning of multimedia. Published with Apple 
Computer, Inc. 

350 pages, 7% x 9%, softcover, $24.95 ISBN 1-55615-124-1 


Microsoft Press books are available wherever books and software are sold. 
Or you can place a credit card order by calling 1-800-888-3303. 


U.S.A. 
U.K. 


Austral. 


(recommended) 


MICRO S OF T* 


Programmer’ 
 OS/2 eae 
Including Presentation Manager 


The MICROSOFT OS/2 PROGRAMMER’S REFERENCE LIBRARY is a low-cost 
way to explore Presentation Manager’s Application Programming Interface (API) and 
start creating intuitive, easy-to-use software applications for its graphical environ- 
ment. The library of four volumes—companions to the affordably priced Microsoft 
OS/2 Presentation Manager Softset development tools —is packed with detailed infor- 
mation on every MS® OS/2 system function, related data types, macros, structures, 
messages, and file formats. 

Each volume in the series is written by a team of OS/2 specialists —many in- 
volved in the development and ongoing enhancement of OS/2 at Microsoft. The 
MICROSOFT OS/2 PROGRAMMER’S REFERENCE LIBRARY is the cornerstone 
of every OS/2 developer’s programming library. 


Volume 1 


Volume | details the conceptual framework of the MS OS/2 Application Programming 
Interface (API). Included are thorough descriptions of MS OS/2 programming models, 
overviews of basic programming considerations, and explanations of the interaction 
between the API and the rest of the MS OS/2 system. Sections include /ntroducing MS 
OS/2; Window Manager; Graphics Programming Interface; and System Services. 


Volume 2 


Volume 2 is a comprehensive, alphabetic listing of MS OS/2 Presentation Manager 
version 1.1 functions and of the structures used with these functions. Each function 
entry includes information on syntax; descriptions of the function’s actions and pur- 
pose; parameters and field definitions; return values, error values, and restrictions; 
source-code examples; and programming notes. A separate chapter discusses file for- 
mats. Appendixes cover error values and device capabilities. 


Volume 3 


Similar in format to Volume 2, Volume 3 is a comprehensive, alphabetic listing of MS 
OS/2 version 1.1 base functions, including their structures and file formats. Appen- 
dixes cover error values and ANSI escape sequences. 


Volume 4 


Volume 4 contains information on the new API elements in MS OS/2 version 1.2, as 
well as updated information on version 1.1 functions, 
structures, and messages. 


$19.95 
£18.95 
$29.95 


